@shortlink-org/portolan 0.1.0

package/src/language/InLanguage.tsx

@@ -0,0 +1,40 @@
+// What the glossary calls the thing this page is about.
+//
+// One line, under the header, before the model: a reader who does not know
+// what the word means in this context cannot read the page below it, and the
+// sentence that says so is already written - in a file next to the code, by
+// somebody who knows.
+//
+// It appears only where the glossary and the code spell the word the same
+// way. That is most of the words worth knowing and nowhere near all of them,
+// and the page says nothing at all when there is no pairing: a strip reading
+// "no definition" on two thirds of the estate would be a lint nobody asked
+// for, printed on every page.
+
+import { Link } from "react-router";
+import { catalog } from "../data";
+import { paths } from "../routes";
+import { bindTerms } from "../lib/terms";
+
+// Built once, from the catalog the app ships, exactly as the palette builds
+// its index: the pairing is a property of the estate, not of a render.
+const BOUND = bindTerms(catalog);
+
+export function InLanguage({ id }: { id: string }) {
+  const term = BOUND.byTarget.get(id);
+  if (!term) return null;
+
+  return (
+    <p className="mb-3 max-w-prose text-muted">
+      <Link
+        to={paths.term(term.id)}
+        className="rounded-control font-medium text-ink hover:underline"
+        title={`${term.id} — in the glossary of ${term.context}`}
+      >
+        {term.name}
+      </Link>
+      {" — "}
+      {term.definition}
+    </p>
+  );
+}

package/src/language/TermCard.tsx

@@ -0,0 +1,132 @@
+// One entry of a glossary, as a card: the word, and what it means.
+//
+// The slug is not drawn. `Bus` and `bus` beside each other is the same word
+// printed twice, and the id it would have carried is on the copy button that
+// every row in this app has.
+
+import { Fragment } from "react";
+import { Link } from "react-router";
+import type { Term } from "../catalog";
+import { KindIcon } from "../components/kind";
+import type { TermTarget } from "../lib/terms";
+import { RowActions } from "../components/RowActions";
+import { ContextPill } from "../components/primitives";
+import { ctxStyle } from "../lib/context-color";
+import { sourceHref } from "../lib/source-link";
+import { staggerStyle } from "../lib/motion";
+
+/**
+ * Backticks, and nothing else.
+ *
+ * A glossary is prose with the occasional identifier in it - `logout`, the
+ * name of a service - and every other mark the format allows is already gone
+ * by the time a term reaches the catalog. So this is a split on backticks and
+ * not a markdown renderer: one react-markdown per card, thirty-eight of them
+ * on a page, to italicise nothing.
+ */
+function inline(text: string) {
+  return text.split("`").map((part, i) =>
+    i % 2 === 1 ? (
+      <code key={i} className="mono">
+        {part}
+      </code>
+    ) : (
+      <Fragment key={i}>{part}</Fragment>
+    ),
+  );
+}
+
+export function TermCard({
+  term,
+  targets = [],
+  index = 0,
+  showContext = false,
+}: {
+  term: Term;
+  /**
+   * What the word names in the model, when the two spell it the same way.
+   * Empty is the ordinary case for the words worth defining - Bus, Refusal,
+   * Conflict name no type - so the row simply does not appear, and nothing on
+   * the card says anything is missing.
+   */
+  targets?: readonly TermTarget[];
+  /** Position in the list, for the staggered entrance. */
+  index?: number;
+  /**
+   * Names the context on the card. Off inside a vocabulary, whose heading has
+   * already said it; on where cards from several contexts stand together, and
+   * there the context is the only thing telling two of them apart.
+   */
+  showContext?: boolean;
+}) {
+  const href = sourceHref(term.source, null);
+
+  return (
+    <div
+      id={`term-${term.id}`}
+      /* A column, so the row of cards can be one height and the line under
+         the definition still sits on the floor of each of them. Stretched to
+         its neighbours and left alone, a short entry grows a pocket of empty
+         card under its last sentence. */
+      className="card card-static stagger-in flex flex-col scroll-mt-4"
+      style={{ ...staggerStyle(index), ...ctxStyle(term.context), borderLeftWidth: 3 }}
+    >
+      <div className="flex items-baseline gap-2">
+        <h3 className="font-semibold">{term.name}</h3>
+        {showContext ? (
+          <span className="ml-auto shrink-0">
+            <ContextPill id={term.context} />
+          </span>
+        ) : null}
+      </div>
+
+      <p className="mt-1.5">{inline(term.definition)}</p>
+
+      {targets.length > 0 ? (
+        <div className="mt-2 flex flex-wrap items-center gap-1.5">
+          {targets.map((target) => (
+            <Link
+              key={target.id}
+              to={target.path}
+              className="chip hover:border-line-strong hover:text-ink"
+              title={`${target.kind} ${target.id}`}
+            >
+              {/* A state is not one of the app's kinds - it has no page and no
+                  mark of its own - so it wears a dot rather than borrowing an
+                  icon that would say it was something it is not. */}
+              {target.kind === "state" ? (
+                <span aria-hidden className="dot" />
+              ) : (
+                <KindIcon kind={target.kind} />
+              )}
+              {target.name}
+            </Link>
+          ))}
+        </div>
+      ) : null}
+
+      {/* Where the entry was written, and the button that copies its id, on one
+          line under the definition. The copy sat in the heading before, which
+          put a button between the word and the context that means it - two
+          things a reader compares across cards, and a control that appears
+          between them on hover is a control that moves them apart. */}
+      <div className="mt-auto flex items-baseline gap-2 pt-2 t-micro">
+        {href ? (
+          <a
+            href={href}
+            target="_blank"
+            rel="noreferrer"
+            className="mono text-faint hover:text-accent"
+          >
+            {term.source}
+          </a>
+        ) : (
+          /* Not a link, but still the answer to "where do I change this?" -
+             the same way every unlinkable path in this app stays text. */
+          <span className="mono text-faint">{term.source}</span>
+        )}
+        <RowActions copy={term.id} label={term.name} />
+      </div>
+    </div>
+  );
+}

package/src/language/cards.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../testing/estate";
+import type { Catalog, Term } from "../catalog";
+import { homonyms, matchTerms, vocabularies } from "./cards";
+
+const term = (id: string, context: string, slug: string, name = slug): Term => ({
+  id,
+  slug,
+  context,
+  name,
+  definition: "one sentence.",
+  source: "GLOSSARY.md:1",
+});
+
+/** A catalog with only what these functions read. */
+const of = (terms: Term[], contexts: string[] = ["auth", "shop"]): Catalog =>
+  ({
+    contexts: contexts.map((id) => ({ id, slug: id, name: id, services: [] })),
+    terms,
+  }) as unknown as Catalog;
+
+describe("vocabularies", () => {
+  it("groups by context, in catalog order, alphabetical inside", () => {
+    const arranged = vocabularies(
+      of([
+        term("shop.order", "shop", "order", "Order"),
+        term("auth.session", "auth", "session", "Session"),
+        term("auth.attempt", "auth", "attempt", "Attempt"),
+      ]),
+    );
+
+    expect(arranged.map((v) => v.contextId)).toEqual(["auth", "shop"]);
+    expect(arranged[0]?.terms.map((t) => t.name)).toEqual([
+      "Attempt",
+      "Session",
+    ]);
+  });
+
+  it("leaves out a context that has written no glossary", () => {
+    const arranged = vocabularies(of([term("auth.session", "auth", "session")]));
+
+    expect(arranged).toHaveLength(1);
+  });
+
+  // The validator refuses this catalog, so nothing should ever render it. The
+  // arrangement still shows the terms rather than dropping them: a list that
+  // silently loses rows is the harder bug of the two.
+  it("still shows terms whose context the catalog does not declare", () => {
+    const arranged = vocabularies(of([term("oms.order", "oms", "order")]));
+
+    expect(arranged).toHaveLength(1);
+    expect(arranged[0]?.context).toBeNull();
+    expect(arranged[0]?.contextId).toBe("oms");
+  });
+});
+
+describe("homonyms", () => {
+  it("finds one word meant in two contexts", () => {
+    const found = homonyms(
+      of([
+        term("auth.bus", "auth", "bus", "Bus"),
+        term("shop.bus", "shop", "bus", "Bus"),
+        term("auth.session", "auth", "session", "Session"),
+      ]),
+    );
+
+    expect(found).toHaveLength(1);
+    expect(found[0]?.word).toBe("Bus");
+    expect(found[0]?.terms.map((t) => t.context)).toEqual(["auth", "shop"]);
+  });
+
+  it("says nothing about a word only one context uses", () => {
+    expect(homonyms(of([term("auth.session", "auth", "session")]))).toEqual([]);
+  });
+
+  // What the estate actually has, and the reason the section exists: two
+  // services describe the same piece of plumbing in their own words.
+  it("finds the words the example estate means twice", () => {
+    expect(homonyms(catalog).map((h) => h.slug)).toEqual(["bus", "outbox"]);
+  });
+});
+
+describe("matchTerms", () => {
+  const terms = [
+    {
+      ...term("auth.session", "auth", "session", "Session"),
+      definition:
+        "Proof that a user logged in, and the token it is presented with.",
+    },
+    {
+      ...term("auth.lockout", "auth", "lockout", "Lockout"),
+      definition: "An account refusing passwords for a while.",
+    },
+  ];
+
+  it("matches on the name", () => {
+    expect(matchTerms(terms, "lock").map((t) => t.name)).toEqual(["Lockout"]);
+  });
+
+  it("matches on the definition, not only the word", () => {
+    expect(matchTerms(terms, "token").map((t) => t.name)).toEqual(["Session"]);
+  });
+
+  it("takes every word, in any order", () => {
+    expect(matchTerms(terms, "passwords account").map((t) => t.name)).toEqual([
+      "Lockout",
+    ]);
+    expect(matchTerms(terms, "passwords token")).toEqual([]);
+  });
+
+  it("answers an empty query with everything", () => {
+    expect(matchTerms(terms, "   ")).toHaveLength(2);
+  });
+});

package/src/language/cards.ts

@@ -0,0 +1,111 @@
+// The glossary, arranged for reading. Pure: a catalog in, plain values out,
+// so what the page shows can be asserted in a test rather than eyeballed.
+//
+// Two arrangements, and the second is the one that earns the page. A context's
+// vocabulary is a list anyone could have written by hand; the words that mean
+// two things in two contexts are only visible once every glossary in the
+// estate is in one place, and they are exactly what a reader crossing a
+// boundary gets wrong.
+
+import type { BoundedContext, Catalog, Term } from "../catalog";
+import { allTerms } from "../catalog";
+
+/** One context's words, alphabetical, however the sources were ordered. */
+export interface Vocabulary {
+  contextId: string;
+  /** The context itself, when the catalog declares one. */
+  context: BoundedContext | null;
+  terms: Term[];
+}
+
+function byName(a: Term, b: Term): number {
+  return a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+}
+
+/**
+ * Every vocabulary, in catalog order - which is the order the contexts are
+ * drawn in everywhere else, so the page reads in the same direction as the
+ * sidebar and the map.
+ */
+export function vocabularies(catalog: Catalog): Vocabulary[] {
+  const byContext = new Map<string, Term[]>();
+  for (const term of allTerms(catalog)) {
+    const list = byContext.get(term.context) ?? [];
+    list.push(term);
+    byContext.set(term.context, list);
+  }
+
+  const out: Vocabulary[] = [];
+  for (const context of catalog.contexts) {
+    const terms = byContext.get(context.id);
+    if (!terms) continue;
+    out.push({ contextId: context.id, context, terms: [...terms].sort(byName) });
+    byContext.delete(context.id);
+  }
+  // A glossary whose context is not in the catalog cannot happen - the
+  // validator refuses it - but the arrangement does not depend on that being
+  // true, because a list that silently drops rows is worse than one that
+  // shows them somewhere plain.
+  for (const [contextId, terms] of byContext) {
+    out.push({ contextId, context: null, terms: [...terms].sort(byName) });
+  }
+
+  return out;
+}
+
+/** One word, and the contexts that mean different things by it. */
+export interface Homonym {
+  /** The shared slug - what makes two spellings one word. */
+  slug: string;
+  /** As the glossaries spell it, taking the first if they disagree in case. */
+  word: string;
+  terms: Term[];
+}
+
+/**
+ * The words that appear in more than one context.
+ *
+ * Not a problem to fix. `User` in auth is an id, an email and a hash; `User`
+ * in shop is a name and an address - two entries is the correct answer, and
+ * the layout rules say so. What is worth seeing is that a reader crossing the
+ * boundary is now holding two meanings of one word, which no single glossary
+ * can tell them.
+ */
+export function homonyms(catalog: Catalog): Homonym[] {
+  const bySlug = new Map<string, Term[]>();
+  for (const term of allTerms(catalog)) {
+    const list = bySlug.get(term.slug) ?? [];
+    list.push(term);
+    bySlug.set(term.slug, list);
+  }
+
+  const out: Homonym[] = [];
+  for (const [slug, terms] of bySlug) {
+    // Two entries of one context cannot happen either - the merge reports it -
+    // so counting contexts rather than terms is the honest test of "the same
+    // word, twice".
+    if (new Set(terms.map((t) => t.context)).size < 2) continue;
+    out.push({
+      slug,
+      word: terms[0]?.name ?? slug,
+      terms: [...terms].sort((a, b) => a.context.localeCompare(b.context)),
+    });
+  }
+
+  return out.sort((a, b) => a.word.localeCompare(b.word));
+}
+
+/**
+ * The filter box: every word of the query has to appear somewhere in the
+ * entry, in any order.
+ */
+export function matchTerms(terms: Term[], query: string): Term[] {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return terms;
+
+  return terms.filter((term) => {
+    const haystack =
+      `${term.name} ${term.slug} ${term.definition}`.toLowerCase();
+    return words.every((word) => haystack.includes(word));
+  });
+}

package/src/lib/admonition.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import {
+  ADMONITION_KINDS,
+  ADMONITION_LABEL,
+  parseAdmonition,
+} from "./admonition";
+
+describe("GitHub admonitions", () => {
+  it("labels every kind it claims to know", () => {
+    for (const kind of ADMONITION_KINDS) {
+      expect(ADMONITION_LABEL[kind], kind).toBeTruthy();
+    }
+  });
+
+  it("reads the marker and hands back the body", () => {
+    for (const kind of ADMONITION_KINDS) {
+      const marker = `[!${kind.toUpperCase()}]`;
+      expect(parseAdmonition(`${marker}\nMind this.`)).toEqual({
+        kind,
+        rest: "Mind this.",
+      });
+    }
+  });
+
+  it("accepts a marker that stands alone", () => {
+    expect(parseAdmonition("[!NOTE]")).toEqual({ kind: "note", rest: "" });
+    expect(parseAdmonition("[!NOTE]\n")).toEqual({ kind: "note", rest: "" });
+  });
+
+  it("tolerates the case and the trailing spaces a writer leaves behind", () => {
+    expect(parseAdmonition("[!Warning]  \nCareful.")).toEqual({
+      kind: "warning",
+      rest: "Careful.",
+    });
+  });
+
+  it("keeps the rest of a multi-line body intact", () => {
+    expect(parseAdmonition("[!TIP]\nfirst\nsecond")?.rest).toBe(
+      "first\nsecond",
+    );
+  });
+
+  it("refuses anything that is not a bare marker line", () => {
+    expect(parseAdmonition("[!NOTE] on the same line")).toBeNull();
+    expect(parseAdmonition("[!HINT]\nnot a GitHub kind")).toBeNull();
+    expect(parseAdmonition("A quotation.")).toBeNull();
+    expect(parseAdmonition("text before\n[!NOTE]\nafter")).toBeNull();
+  });
+});

package/src/lib/admonition.ts

@@ -0,0 +1,48 @@
+// GitHub's alert syntax: a blockquote whose first line is a bare `[!NOTE]`
+// marker. It turns up in any README written on GitHub, so Portolan renders the
+// five kinds GitHub knows and leaves everything else a plain quotation - the
+// same rule GitHub itself applies to `[!HINT]`.
+
+export const ADMONITION_KINDS = [
+  "note",
+  "tip",
+  "important",
+  "warning",
+  "caution",
+] as const;
+
+export type AdmonitionKind = (typeof ADMONITION_KINDS)[number];
+
+export const ADMONITION_LABEL: Record<AdmonitionKind, string> = {
+  note: "Note",
+  tip: "Tip",
+  important: "Important",
+  warning: "Warning",
+  caution: "Caution",
+};
+
+/**
+ * The marker owns its whole line: `[!NOTE] see below` is prose that happens to
+ * start with brackets, not an alert. Matching is case-insensitive, as it is in
+ * cmark-gfm, but the label always comes back canonical.
+ */
+const MARKER = /^\[!([a-z]+)\][^\S\n]*(?:\r?\n|$)/i;
+
+function isKind(word: string): word is AdmonitionKind {
+  return (ADMONITION_KINDS as readonly string[]).includes(word);
+}
+
+/**
+ * Reads the marker off the first text of a blockquote. `rest` is what is left
+ * of that text once the marker line is gone - usually the alert's first
+ * sentence, empty when the marker stands alone.
+ */
+export function parseAdmonition(
+  text: string,
+): { kind: AdmonitionKind; rest: string } | null {
+  const match = MARKER.exec(text);
+  if (!match) return null;
+  const kind = match[1]?.toLowerCase() ?? "";
+  if (!isKind(kind)) return null;
+  return { kind, rest: text.slice(match[0].length) };
+}

package/src/lib/adr.test.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { catalog } from "../testing/estate";
+import {
+  adrCoversService,
+  adrNumber,
+  adrsForService,
+  isCurrent,
+  newestAccepted,
+  sortAdrs,
+} from "./adr";
+import type { Adr } from "../catalog";
+
+function byId(id: string): Adr {
+  const adr = catalog.adrs.find((a) => a.id === id);
+  if (!adr) throw new Error(`no adr ${id}`);
+  return adr;
+}
+
+describe("adrNumber", () => {
+  it("pads to the four digits people write in commits", () => {
+    expect(adrNumber(byId("org.0001"))).toBe("ADR-0001");
+    expect(adrNumber(byId("shop.oms.0007"))).toBe("ADR-0007");
+  });
+});
+
+describe("sortAdrs", () => {
+  it("puts the newest decision first", () => {
+    expect(sortAdrs(catalog.adrs).map((a) => a.id)).toEqual([
+      "shop.oms.0007",
+      "payments.0004",
+      "shop.oms.0003",
+      "org.0002",
+      "org.0001",
+    ]);
+  });
+
+  it("does not mutate its input", () => {
+    const before = catalog.adrs.map((a) => a.id);
+    sortAdrs(catalog.adrs);
+    expect(catalog.adrs.map((a) => a.id)).toEqual(before);
+  });
+});
+
+describe("isCurrent", () => {
+  it("is false for records that no longer hold", () => {
+    expect(isCurrent(byId("shop.oms.0003"))).toBe(false);
+    expect(isCurrent(byId("shop.oms.0007"))).toBe(true);
+    expect(isCurrent(byId("payments.0004"))).toBe(true);
+  });
+});
+
+describe("adrCoversService", () => {
+  const org = byId("org.0002");
+  const context = byId("payments.0004");
+  const service = byId("shop.oms.0007");
+  const relates = byId("org.0001");
+
+  it("lets an org decision govern every service", () => {
+    expect(adrCoversService(org, "shop.pricing", "shop")).toBe(true);
+    expect(adrCoversService(org, "delivery.core", "delivery")).toBe(true);
+  });
+
+  it("scopes a context decision to that context only", () => {
+    expect(adrCoversService(context, "payments.ledger", "payments")).toBe(true);
+    expect(adrCoversService(context, "shop.oms", "shop")).toBe(false);
+  });
+
+  it("scopes a service decision to that service only", () => {
+    expect(adrCoversService(service, "shop.oms", "shop")).toBe(true);
+    expect(adrCoversService(service, "shop.pricing", "shop")).toBe(false);
+  });
+
+  it("also covers services named in relates", () => {
+    expect(relates.scope.kind).toBe("org");
+    const narrowed: Adr = {
+      ...relates,
+      scope: { kind: "context", context: "shop" },
+    };
+    expect(adrCoversService(narrowed, "delivery.core", "delivery")).toBe(true);
+    expect(adrCoversService(narrowed, "shop.pricing", "shop")).toBe(true);
+    expect(adrCoversService(narrowed, "payments.ledger", "payments")).toBe(
+      false,
+    );
+  });
+});
+
+describe("adrsForService", () => {
+  it("lists everything governing shop.oms, newest first", () => {
+    expect(
+      adrsForService(catalog, "shop.oms", "shop").map((a) => a.id),
+    ).toEqual(["shop.oms.0007", "shop.oms.0003", "org.0002", "org.0001"]);
+  });
+
+  it("gives shop.pricing only the org-wide decisions", () => {
+    expect(
+      adrsForService(catalog, "shop.pricing", "shop").map((a) => a.id),
+    ).toEqual(["org.0002", "org.0001"]);
+  });
+
+  it("gives payments.ledger its own context's decision too", () => {
+    expect(
+      adrsForService(catalog, "payments.ledger", "payments").map((a) => a.id),
+    ).toEqual(["payments.0004", "org.0002", "org.0001"]);
+  });
+});
+
+describe("newestAccepted", () => {
+  it("skips proposed and superseded records", () => {
+    expect(newestAccepted(catalog, 5).map((a) => a.id)).toEqual([
+      "shop.oms.0007",
+      "org.0002",
+      "org.0001",
+    ]);
+  });
+
+  it("honours the limit", () => {
+    expect(newestAccepted(catalog, 1).map((a) => a.id)).toEqual([
+      "shop.oms.0007",
+    ]);
+  });
+});
+
+describe("decision pages draw nothing from the current model", () => {
+  it("never reaches for a LikeC4 view", () => {
+    // A record is frozen history. Rendering a live view inside one would make
+    // it re-draw from a model that has moved on since the decision was taken.
+    const source = readFileSync("src/pages/AdrDetail.tsx", "utf8");
+    expect(source).not.toMatch(/LikeC4View|C4View|FlowView|likec4/);
+  });
+});