@shortlink-org/portolan 0.1.0

package/src/components/kind.tsx

@@ -0,0 +1,157 @@
+// The visual half of the taxonomy in src/lib/kinds.ts. One icon per kind,
+// painted from a token, so nothing downstream picks its own glyph or colour.
+
+import {
+  Database,
+  Eye,
+  Globe,
+  Hexagon,
+  ListChecks,
+  Package,
+  Route,
+  ScrollText,
+  Server,
+  Shapes,
+  Table2,
+  Webhook,
+  WholeWord,
+} from "lucide-react";
+import type { Kind } from "../lib/kinds";
+import { ctxStyle } from "../lib/context-color";
+import {
+  CommandIcon,
+  EntityIcon,
+  EventIcon,
+  QueryIcon,
+  ValueObjectIcon,
+} from "./ddd-icons";
+
+/**
+ * Anything that takes `size` and paints itself from `currentColor` - lucide's
+ * icons and portolan's own five, which are drawn on lucide's grid precisely so
+ * this type can cover both.
+ */
+type IconComponent = (props: {
+  size?: number;
+  className?: string;
+  style?: React.CSSProperties;
+  "aria-hidden"?: boolean;
+}) => React.ReactNode;
+
+/**
+ * The five DDD building blocks are drawn in ./ddd-icons; everything else is
+ * app chrome and stays lucide. That split is the rule, not a coincidence: a
+ * domain concept gets a mark that says what it is, a piece of furniture gets
+ * the furniture library.
+ */
+const KIND_ICON: Record<Kind, IconComponent> = {
+  context: Hexagon, // unused: contexts draw a coloured dot instead
+  // Outside the estate, so the one mark that says "the rest of the world".
+  external: Globe,
+  service: Server,
+  aggregate: Hexagon,
+  // A store and a table are infrastructure, not domain objects, so they take
+  // lucide's furniture rather than one of portolan's five domain marks.
+  store: Database,
+  table: Table2,
+  // A view is drawn as an eye rather than a second grid: what separates it
+  // from a table is that it is a way of LOOKING at rows, not a place they are.
+  view: Eye,
+  event: EventIcon,
+  vo: ValueObjectIcon,
+  entity: EntityIcon,
+  // An enum is a list a consumer ticks through - one of these, and no other.
+  // Furniture rather than a sixth domain mark: the five say what a block IS,
+  // and a set of values is what a field HOLDS.
+  enum: ListChecks,
+  command: CommandIcon,
+  query: QueryIcon,
+  // An endpoint is a door in the wall of a service, not a domain object, so it
+  // takes furniture like the store and the table do.
+  endpoint: Webhook,
+  // A module is a package of schema someone published - infrastructure again,
+  // and a box is what a registry hands you.
+  module: Package,
+  def: Shapes,
+  flow: Route,
+  adr: ScrollText,
+  // A term is a word, and the mark says so. It is deliberately NOT one of the
+  // five domain marks: the glossary names the building blocks, it is not one
+  // of them, and a term wearing an aggregate's hexagon would say it was.
+  term: WholeWord,
+};
+
+/**
+ * Colour by kind. Domain events are the loudest leaf in the tree because they
+ * are the thing other contexts actually depend on; structural blocks stay grey
+ * so they read as detail inside the aggregate that owns them.
+ */
+export const KIND_COLOR: Record<Kind, string> = {
+  context: "var(--ctx)",
+  external: "var(--fg-muted)",
+  service: "var(--fg-muted)",
+  aggregate: "var(--fg)",
+  store: "var(--fg-muted)",
+  table: "var(--fg-muted)",
+  view: "var(--fg-muted)",
+  event: "var(--kind-event)",
+  vo: "var(--fg-muted)",
+  entity: "var(--fg-muted)",
+  enum: "var(--fg-muted)",
+  command: "var(--fg-muted)",
+  query: "var(--fg-muted)",
+  endpoint: "var(--fg-muted)",
+  module: "var(--fg-muted)",
+  def: "var(--fg-muted)",
+  flow: "var(--fg-muted)",
+  adr: "var(--fg-muted)",
+  // A term is painted by the context that means it, like a context row: which
+  // vocabulary a word belongs to is the whole of what distinguishes two
+  // entries that spell the same word.
+  term: "var(--ctx)",
+};
+
+/**
+ * Icons are 16px wherever one stands on its own - a toolbar button, a page
+ * header, the panel's close. Inside a 12px mono row or chip the default drops
+ * to 14: the icon labels the identifier next to it, and a 16px glyph beside
+ * 12px type reads as the subject rather than the label.
+ */
+export function KindIcon({
+  kind,
+  contextId,
+  size = 14,
+  className = "",
+}: {
+  kind: Kind;
+  /** Required for `context`, which is painted in that context's own colour. */
+  contextId?: string;
+  size?: number;
+  className?: string;
+}) {
+  if (kind === "context") {
+    return (
+      <span
+        aria-hidden
+        className={`inline-block shrink-0 rounded-full ${className}`}
+        style={{
+          width: size - 3,
+          height: size - 3,
+          background: "var(--ctx)",
+          ...ctxStyle(contextId),
+        }}
+      />
+    );
+  }
+  const Icon = KIND_ICON[kind];
+  return (
+    <Icon
+      size={size}
+      aria-hidden
+      /* `block` drops the inline baseline gap so the glyph centres on the
+         cap-height of the text beside it rather than sitting on its baseline. */
+      className={`block shrink-0 ${className}`}
+      style={{ color: KIND_COLOR[kind] }}
+    />
+  );
+}

package/src/components/logo.tsx

@@ -0,0 +1,61 @@
+// The mark.
+//
+// A portolan chart is drawn around wind roses: a circle with the rhumb lines
+// radiating out of it, one long point for each cardinal direction and a shorter
+// one between. That is the whole logo - no gradient, no second colour, nothing
+// that stops being a logo at 16px.
+//
+// The star is filled and the ring is stroked, which is the only reason the
+// points still read as points at favicon size: eight hairlines crossing inside
+// a 16px box turn into a grey smudge, eight solid wedges do not.
+
+import type { SVGProps } from "react";
+
+/** The 8-point rose, tips crossing a ring, drawn on the same 24 grid as the icons. */
+export const ROSE_STAR =
+  "M 12 1.4 L 12.96 9.69 L 16.38 7.62 L 14.31 11.04 L 22.6 12 L 14.31 12.96 L 16.38 16.38 L 12.96 14.31 L 12 22.6 L 11.04 14.31 L 7.62 16.38 L 9.69 12.96 L 1.4 12 L 9.69 11.04 L 7.62 7.62 L 11.04 9.69 Z";
+
+export function CompassRose({
+  size = 16,
+  ...rest
+}: Omit<SVGProps<SVGSVGElement>, "ref"> & { size?: number }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-hidden
+      {...rest}
+    >
+      <circle
+        cx={12}
+        cy={12}
+        r={7.1}
+        stroke="currentColor"
+        strokeWidth={1.4}
+        opacity={0.55}
+      />
+      <path d={ROSE_STAR} fill="currentColor" />
+    </svg>
+  );
+}
+
+/**
+ * Mark plus wordmark, for the sidebar header. Lowercase and set in the mono
+ * face: the name is an identifier like everything else this app names.
+ */
+export function Wordmark({ size = 16 }: { size?: number }) {
+  return (
+    <span className="flex items-center gap-2 text-ink">
+      <CompassRose size={size} className="shrink-0" />
+      <span
+        className="text-sm font-semibold lowercase"
+        style={{ letterSpacing: "-0.01em" }}
+      >
+        portolan
+      </span>
+    </span>
+  );
+}

package/src/components/primitives.tsx

@@ -0,0 +1,264 @@
+import { Link } from "react-router";
+import type { ReactNode } from "react";
+import type {
+  Adr,
+  AdrScope,
+  AdrStatus,
+  Classification,
+  Status,
+} from "../catalog";
+import { index } from "../data";
+import { adrNumber } from "../lib/adr";
+import { ctxStyle } from "../lib/context-color";
+import { paths } from "../routes";
+
+const STATUS_LABEL: Record<Status, string> = {
+  verified: "verified",
+  declared: "declared",
+  unresolved: "unresolved",
+};
+
+/** Component class that paints text and border for a status. */
+const STATUS_CLASS: Record<Status, string> = {
+  verified: "status-verified",
+  declared: "status-declared",
+  unresolved: "status-unresolved",
+};
+
+/** Raw value, for SVG strokes and React Flow edges that cannot take a class. */
+export function statusVar(status: Status): string {
+  return `var(--status-${status})`;
+}
+
+export function StatusChip({
+  status,
+  title,
+}: {
+  status: Status;
+  title?: string;
+}) {
+  return (
+    <span
+      title={title ?? `status: ${status}`}
+      className={`chip ${STATUS_CLASS[status]}`}
+    >
+      <span aria-hidden className="dot" />
+      {STATUS_LABEL[status]}
+    </span>
+  );
+}
+
+export function ContextPill({ id, name }: { id: string; name?: string }) {
+  return (
+    <span className="chip ctx" style={ctxStyle(id)}>
+      <span aria-hidden className="dot" />
+      {name ?? id}
+    </span>
+  );
+}
+
+/**
+ * How strategically a bounded context is rated, said in one word. Core is the
+ * only one worth the accent - "supporting" and "generic" are the answer "not
+ * where the value is", and a row full of loud badges says nothing at all.
+ */
+const CLASSIFICATION_META: Record<
+  Classification,
+  { className: string; title: string }
+> = {
+  core: {
+    className: "border-accent text-accent",
+    title: "core domain - where this estate competes",
+  },
+  supporting: {
+    className: "border-line-strong text-muted",
+    title: "supporting domain - needed here, but not a differentiator",
+  },
+  generic: {
+    className: "border-line-strong text-muted",
+    title: "generic domain - a solved problem, bought or borrowed",
+  },
+};
+
+/**
+ * The classification badge, and the only place it is drawn. A context with no
+ * classification renders nothing: an unrated domain is not a "generic" one, and
+ * a placeholder would state a call the estate has not made.
+ *
+ * `tiny` is the sidebar's 10px variant, where the badge rides at the end of a
+ * tree row and must not compete with the context name it annotates.
+ */
+export function ClassificationBadge({
+  classification,
+  tiny = false,
+}: {
+  classification?: Classification;
+  tiny?: boolean;
+}) {
+  if (!classification) return null;
+  const meta = CLASSIFICATION_META[classification];
+  return (
+    <span
+      className={`chip shrink-0 ${meta.className}`}
+      style={tiny ? { fontSize: 10, lineHeight: "14px" } : undefined}
+      title={meta.title}
+    >
+      {classification}
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Decision records
+// ---------------------------------------------------------------------------
+
+/**
+ * Green for what holds, amber for what is still being argued, grey for what is
+ * only history. Grey covers three different endings, so the badge says which.
+ */
+const ADR_STATUS_CLASS: Record<AdrStatus, string> = {
+  accepted: "status-verified",
+  proposed: "status-declared",
+  superseded: "border-line-strong text-muted",
+  deprecated: "border-line-strong text-muted",
+  rejected: "border-line-strong text-muted",
+};
+
+/** True for records that are no longer in force; their number is struck out. */
+export function isStruck(status: AdrStatus): boolean {
+  return status === "superseded" || status === "deprecated";
+}
+
+export function AdrStatusChip({ status }: { status: AdrStatus }) {
+  return (
+    <span
+      title={`status: ${status}`}
+      className={`chip ${ADR_STATUS_CLASS[status]}`}
+    >
+      <span aria-hidden className="dot" />
+      {status}
+    </span>
+  );
+}
+
+/** "ADR-0007", struck through once the decision no longer holds. */
+export function AdrNumber({
+  adr,
+  className = "",
+}: {
+  adr: Adr;
+  className?: string;
+}) {
+  const struck = isStruck(adr.status);
+  return (
+    <span
+      className={`mono ${struck ? "line-through text-muted" : ""} ${className}`}
+      title={struck ? `${adr.id} - no longer in force` : adr.id}
+    >
+      {adrNumber(adr)}
+    </span>
+  );
+}
+
+/**
+ * The scope a decision was taken at, linking to the page it governs. Pass
+ * `link={false}` inside a row that is itself a link: an anchor cannot contain
+ * another one.
+ */
+export function AdrScopePill({
+  scope,
+  link = true,
+}: {
+  scope: AdrScope;
+  link?: boolean;
+}) {
+  if (scope.kind === "org") {
+    return (
+      <span className="chip border-line-strong text-muted" title="org-wide">
+        <span aria-hidden className="dot" />
+        org
+      </span>
+    );
+  }
+
+  if (scope.kind === "context") {
+    const body = (
+      <>
+        <span aria-hidden className="dot" />
+        {scope.context}
+      </>
+    );
+    const props = {
+      className: "chip ctx",
+      style: ctxStyle(scope.context),
+      title: `context ${scope.context}`,
+    };
+    return link ? (
+      <Link to={paths.context(scope.context)} {...props}>
+        {body}
+      </Link>
+    ) : (
+      <span {...props}>{body}</span>
+    );
+  }
+
+  const context = index.serviceContext.get(scope.service);
+  const service = index.serviceById.get(scope.service);
+  if (!context || !service) {
+    return (
+      <span className="chip status-unresolved">
+        <span aria-hidden className="dot" />
+        {scope.service}
+      </span>
+    );
+  }
+  const body = (
+    <>
+      <span aria-hidden className="dot" />
+      {scope.service}
+    </>
+  );
+  const props = {
+    className: "chip ctx",
+    style: ctxStyle(context.id),
+    title: `service ${scope.service}`,
+  };
+  return link ? (
+    <Link to={paths.service(context.id, service.slug)} {...props}>
+      {body}
+    </Link>
+  ) : (
+    <span {...props}>{body}</span>
+  );
+}
+
+export function Panel({
+  title,
+  children,
+}: {
+  title: string;
+  children: ReactNode;
+}) {
+  return (
+    <section className="overflow-hidden rounded-card border border-line shadow-xs">
+      <h2 className="label border-b border-line bg-surface px-4 py-2">
+        {title}
+      </h2>
+      <div className="p-4">{children}</div>
+    </section>
+  );
+}
+
+export function ExternalLink({
+  to,
+  children,
+}: {
+  to: string;
+  children: ReactNode;
+}) {
+  return (
+    <Link to={to} className="mono rounded-control text-accent hover:underline">
+      {children}
+    </Link>
+  );
+}

package/src/data.test.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+import { SOURCE_GLOBS } from "./data";
+
+// The site cannot read the manifest: import.meta.glob resolves at build time
+// and needs literals, so the patterns are written out twice - once in
+// portolan.json for the host, once in data.ts for the site. This is what keeps
+// the two copies one list: a source the host merges and the site never loads
+// is a page that exists in docs/ and nowhere on the site.
+describe("the site's source globs", () => {
+  it("are the manifest's sources, in the manifest's order", () => {
+    const manifest = JSON.parse(
+      readFileSync(new URL("../portolan.json", import.meta.url), "utf8"),
+    ) as { sources: string[] };
+    expect([...SOURCE_GLOBS]).toEqual(manifest.sources);
+  });
+});

package/src/data.ts

@@ -0,0 +1,202 @@
+// Single entry point for catalog data.
+//
+// There is no master catalog. The app reads every source it can find, merges
+// them, and validates the union - in that order, because referential integrity
+// is a property of the whole estate and not of any one file. A service that
+// publishes facts about itself next to its own code is a source; so is a
+// hand-written file carrying the prose nobody can generate.
+//
+// Validation happens here, at startup, so a bad generator run is caught before
+// anything is drawn. It is caught, not thrown: a validator that throws out of a
+// module's top level takes the whole bundle down and the reader gets a blank
+// page and a line in a console they are not looking at. So the failure is
+// turned into a value, the app falls back to an empty catalog so every module
+// below still imports, and the shell renders the error instead of the routes.
+
+import { buildIndex, CatalogError, validateCatalog } from "./catalog";
+import type { Catalog, CatalogIndex } from "./catalog";
+import {
+  catalogProfileNamed,
+  catalogProfiles as profilesFromManifest,
+  filterCatalogForProfile,
+  profileIncludesSource,
+} from "./catalog-profile";
+import type { CatalogProfile, CatalogProfileManifest } from "./catalog-profile";
+import { enrichCatalog } from "./enrich";
+import type { DerivedEdge } from "./enrich";
+import { mergeCatalogs } from "./merge";
+import type {
+  CatalogSource,
+  MergeConflict,
+  SourceCatalog,
+  SourceStamp,
+} from "./merge";
+import manifestJson from "../portolan.json";
+
+const manifest = manifestJson as CatalogProfileManifest & { sources: string[] };
+export const catalogProfiles: CatalogProfile[] = profilesFromManifest(manifest);
+const requestedProfile =
+  typeof window === "undefined"
+    ? null
+    : new URLSearchParams(window.location.search).get("catalog");
+export const activeCatalogProfile = catalogProfileNamed(manifest, requestedProfile);
+
+/**
+ * Where sources are looked for. The patterns are written out because
+ * import.meta.glob resolves at build time and needs literals - and because
+ * they are worth reading: the first is the estate's own files, the second is
+ * what each service publishes beside its code - one level down for a context
+ * of one service, two for a context that holds several.
+ */
+export const SOURCE_GLOBS = [
+  "data/*.json",
+  "portolan/*.json",
+  "examples/*/portolan/*.json",
+  "examples/*/*/portolan/*.json",
+  "examples/*/*/*/portolan/*.json",
+  "vendor/repos/*/*/git.repo.json",
+  "vendor/repos/**/portolan/*.json",
+] as const;
+
+const modules: Record<string, unknown> = {
+  ...import.meta.glob("../data/*.json", { eager: true, import: "default" }),
+  ...import.meta.glob("../portolan/*.json", { eager: true, import: "default" }),
+  ...import.meta.glob("../examples/*/portolan/*.json", {
+    eager: true,
+    import: "default",
+  }),
+  ...import.meta.glob("../examples/*/*/portolan/*.json", {
+    eager: true,
+    import: "default",
+  }),
+  ...import.meta.glob("../examples/*/*/*/portolan/*.json", {
+    eager: true,
+    import: "default",
+  }),
+  ...import.meta.glob("../vendor/repos/*/*/git.repo.json", {
+    eager: true,
+    import: "default",
+  }),
+  ...import.meta.glob("../vendor/repos/**/portolan/*.json", {
+    eager: true,
+    import: "default",
+  }),
+};
+
+/** What the app draws when the catalog cannot be trusted: nothing. */
+const EMPTY: Catalog = {
+  generatedAt: "",
+  commit: "",
+  contexts: [],
+  defs: {},
+  flows: [],
+  adrs: [],
+};
+
+interface Loaded {
+  catalog: Catalog;
+  sources: SourceStamp[];
+  conflicts: MergeConflict[];
+  derived: DerivedEdge[];
+  error: CatalogError | null;
+  /** The sources as merged, before anything was derived or checked. */
+  raw: Catalog;
+}
+
+function load(): Loaded {
+  const sources: CatalogSource[] = Object.entries(modules)
+    .map(([path, 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 merged = mergeCatalogs(sources);
+  // Enriched before it is validated: the edges the flows imply are part of
+  // the union the way a peer named by another source is, and the validator
+  // resolves a step's call against them.
+  const scoped = filterCatalogForProfile(merged.catalog, activeCatalogProfile);
+  const enriched = enrichCatalog(scoped);
+
+  try {
+    return {
+      catalog: validateCatalog(enriched.catalog),
+      sources: merged.sources,
+      conflicts: merged.conflicts,
+      derived: enriched.derived,
+      error: null,
+      raw: merged.catalog,
+    };
+  } catch (cause) {
+    const error =
+      cause instanceof CatalogError
+        ? cause
+        : // Anything else is a shape the validator never got far enough to
+          // name - a truncated file, a null where a list was expected. Same
+          // treatment.
+          new CatalogError(
+            cause instanceof Error ? cause.message : String(cause),
+          );
+
+    return {
+      catalog: EMPTY,
+      sources: merged.sources,
+      conflicts: merged.conflicts,
+      derived: [],
+      error,
+      raw: merged.catalog,
+    };
+  }
+}
+
+const loaded = load();
+
+export const catalog: Catalog = loaded.catalog;
+export const index: CatalogIndex = buildIndex(catalog);
+
+/**
+ * The sources the catalog was built from, newest first by nothing at all -
+ * they are in path order, which is the order the merge used.
+ *
+ * This is what the merged stamp is a summary of, and the summary is lossy in
+ * both halves: one date stands for the oldest of many, and "6 sources" stands
+ * for six shas the header has no room to print. The Overview stamp opens onto
+ * this list, so a reader who wants to know WHICH part is a week old can find
+ * out instead of being told a number and left with it. A source with an empty
+ * stamp is one nobody generated.
+ */
+export const catalogSources: SourceStamp[] = loaded.sources;
+
+/**
+ * Sources disagreeing with each other. Not an error: two files both naming a
+ * context is normal, and both naming it differently is a fact about the estate
+ * that belongs on the Problems page rather than on a crash screen.
+ */
+export const catalogConflicts: MergeConflict[] = loaded.conflicts;
+
+/**
+ * Consumers and calls no source declared: what the flows said, written onto
+ * the events and services after the merge. Each one names the step it was
+ * read from, and the catalog above already contains it.
+ */
+export const derivedEdges: DerivedEdge[] = loaded.derived;
+
+/**
+ * Where the catalog is read from, as a reader would type it. Empty states name
+ * it, so it is written once here rather than spelled out on five pages.
+ */
+export const CATALOG_PATH = activeCatalogProfile.sources.join(" · ");
+
+/** Non-null when the catalog failed validation; the shell renders it instead. */
+export const catalogError: CatalogError | null = loaded.error;
+
+/**
+ * The merge before enrichment and validation: what the sources said, with
+ * nothing derived onto it yet. Tests that check the validator, or that want
+ * to see the estate the way a source wrote it, start from here.
+ */
+export const rawCatalog: Catalog = loaded.raw;