@shortlink-org/portolan 0.1.0

package/src/lib/table-directive.ts

@@ -0,0 +1,106 @@
+// The author's say over a table in a README.
+//
+// Enhancement is the default because a README table is usually a list someone
+// would like to sort. It is not always: a two-column key/value block, or a
+// table whose row order IS the content, is worse for being made interactive.
+// So there is an escape hatch, and it is an HTML comment - the one thing that
+// can sit in a markdown file, mean something here, and remain invisible
+// everywhere else the file is read.
+//
+//   <!-- table: static -->            render it as written, no toolbar, no sort
+//   <!-- table: sort=name.desc -->    open it sorted, by column id and direction
+
+/** The attribute the remark plugin leaves on a table for the renderer to find. */
+export const TABLE_DIRECTIVE_ATTR = "data-table";
+
+const COMMENT_RE = /^<!--\s*table:\s*(.*?)\s*-->$/;
+
+export interface TableDirective {
+  /** Render as written: this table is not a list, it is a layout. */
+  static: boolean;
+  /** Column id and direction, as `<id>.asc` or `<id>.desc`. */
+  sort: { id: string; desc: boolean } | null;
+}
+
+export const NO_DIRECTIVE: TableDirective = { static: false, sort: null };
+
+/**
+ * Reads the body of a `table:` comment. Returns null for a comment that is not
+ * one of ours, so an ordinary HTML comment above a table stays an ordinary
+ * HTML comment.
+ */
+export function parseTableComment(raw: string): string | null {
+  const match = COMMENT_RE.exec(raw.trim());
+  return match ? (match[1] ?? "") : null;
+}
+
+/** Reads the directive body. An unrecognised word is ignored, never fatal. */
+export function parseTableDirective(body: string): TableDirective {
+  const directive: TableDirective = { static: false, sort: null };
+  for (const term of body.split(/\s+/)) {
+    if (term === "") continue;
+    if (term === "static") {
+      directive.static = true;
+      continue;
+    }
+    const sort = /^sort=(.+)\.(asc|desc)$/.exec(term);
+    if (sort?.[1]) directive.sort = { id: sort[1], desc: sort[2] === "desc" };
+  }
+  return directive;
+}
+
+/** A column id from a header cell: what the `sort=` directive names. */
+export function columnSlug(header: string, taken: Set<string>): string {
+  const base =
+    header
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "") || "col";
+  if (!taken.has(base)) return base;
+  // Two columns headed the same is a bad table, not an error. Number them.
+  let n = 2;
+  while (taken.has(`${base}-${n}`)) n++;
+  return `${base}-${n}`;
+}
+
+// --- The remark half -------------------------------------------------------
+
+interface Node {
+  type: string;
+  value?: string;
+  data?: { hProperties?: Record<string, string> };
+  children?: Node[];
+}
+
+/**
+ * Attaches a `table:` comment to the table it introduces. remark leaves the
+ * comment as an `html` node and react-markdown drops it, so without this the
+ * directive would be invisible to the component that has to obey it.
+ *
+ * "Introduces" means the node immediately before, at the same level - which
+ * is the only place an author would think to write it.
+ */
+export function remarkTableDirective() {
+  return (tree: Node): void => {
+    const walk = (node: Node): void => {
+      const children = node.children;
+      if (!children) return;
+      for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (!child) continue;
+        walk(child);
+        if (child.type !== "table") continue;
+        const previous = children[i - 1];
+        if (!previous || previous.type !== "html") continue;
+        const body = parseTableComment(previous.value ?? "");
+        if (body === null) continue;
+        child.data = child.data ?? {};
+        child.data.hProperties = {
+          ...child.data.hProperties,
+          [TABLE_DIRECTIVE_ATTR]: body,
+        };
+      }
+    };
+    walk(tree);
+  };
+}

package/src/lib/tech.test.ts

@@ -0,0 +1,120 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { STORE_KINDS } from "../catalog";
+import {
+  STORE_KIND_GLYPH,
+  TECH_MARKS,
+  TECH_WITHOUT_GLYPH,
+  techGlyph,
+  techKey,
+} from "./tech";
+
+/**
+ * The names extract-project can write, read off its own source: every
+ * `{"Name", <seen>}` marker in the technologies table. Reading the Go file
+ * rather than copying the list is the point - a marker added there and
+ * forgotten here is exactly what this test exists to catch.
+ */
+function extractedTechnologies(): string[] {
+  const source = readFileSync(
+    new URL("../../plugins/extract-project/extract.go", import.meta.url),
+    "utf8",
+  );
+  const body = source.slice(source.indexOf("func technologies("));
+  return [...body.matchAll(/^\s*\{"([^"]+)", /gm)].map((m) => m[1] ?? "");
+}
+
+describe("techKey", () => {
+  it("folds case and punctuation", () => {
+    expect(techKey("Node.js")).toBe("nodejs");
+    expect(techKey("NodeJS")).toBe("nodejs");
+    expect(techKey("Apache Kafka")).toBe("apachekafka");
+    expect(techKey("Spring Boot")).toBe("springboot");
+  });
+
+  it("keeps what makes C++ and C# different languages from C", () => {
+    expect(techKey("C++")).toBe("c++");
+    expect(techKey("C#")).toBe("c#");
+    expect(techKey("C")).toBe("c");
+  });
+});
+
+describe("techGlyph", () => {
+  it("answers the same mark for every spelling of one brand", () => {
+    const postgres = techGlyph("PostgreSQL");
+    expect(postgres?.title).toBe("PostgreSQL");
+    for (const spelling of ["postgres", "Postgres", "postgresql", "pg", "psql"]) {
+      expect(techGlyph(spelling), spelling).toEqual(postgres);
+    }
+    expect(techGlyph("nodejs")?.title).toBe("Node.js");
+    expect(techGlyph("Kafka")?.title).toBe("Apache Kafka");
+    expect(techGlyph("k8s")?.title).toBe("Kubernetes");
+  });
+
+  it("answers null for a word with no mark", () => {
+    expect(techGlyph("River")).toBeNull();
+    expect(techGlyph("")).toBeNull();
+    expect(techGlyph("something nobody ships")).toBeNull();
+  });
+
+  it("draws a real path for every mark", () => {
+    for (const mark of TECH_MARKS) {
+      expect(mark.path, mark.title).toMatch(/^[Mm]/);
+      expect(mark.names[0]).toBe(mark.title);
+    }
+  });
+
+  it("gives no name to two marks", () => {
+    const seen = new Map<string, string>();
+    for (const mark of TECH_MARKS) {
+      // An alias that folds to the title's own key is redundant, not a clash.
+      for (const key of new Set(mark.names.map(techKey))) {
+        const name = mark.names.find((n) => techKey(n) === key);
+        expect(
+          seen.get(key),
+          `"${name}" names both ${seen.get(key)} and ${mark.title}`,
+        ).toBeUndefined();
+        seen.set(key, mark.title);
+      }
+    }
+  });
+});
+
+describe("store kind glyphs", () => {
+  it("decides for every store kind, glyph or none", () => {
+    for (const kind of STORE_KINDS) {
+      expect(kind in STORE_KIND_GLYPH).toBe(true);
+    }
+  });
+
+  it("draws the kinds that have a mark and leaves the rest a word", () => {
+    expect(STORE_KIND_GLYPH.postgres?.title).toBe("PostgreSQL");
+    expect(STORE_KIND_GLYPH.redis?.title).toBe("Redis");
+    expect(STORE_KIND_GLYPH.s3).toBeNull();
+    expect(STORE_KIND_GLYPH.other).toBeNull();
+  });
+});
+
+describe("extract-project markers", () => {
+  const markers = extractedTechnologies();
+
+  it("are read off the Go source", () => {
+    expect(markers).toContain("Go");
+    expect(markers).toContain("Kafka");
+    expect(markers.length).toBeGreaterThan(10);
+  });
+
+  it("each have a glyph or are named as having none", () => {
+    for (const name of markers) {
+      const decided = techGlyph(name) !== null || TECH_WITHOUT_GLYPH.includes(name);
+      expect(decided, `${name} has neither a glyph nor a place in TECH_WITHOUT_GLYPH`).toBe(true);
+    }
+  });
+
+  it("are not listed as having none when they have one", () => {
+    for (const name of TECH_WITHOUT_GLYPH) {
+      expect(markers, `${name} is not a name extract-project writes`).toContain(name);
+      expect(techGlyph(name), `${name} has a glyph after all`).toBeNull();
+    }
+  });
+});

package/src/lib/tech.ts

@@ -0,0 +1,421 @@
+// A technology's mark, looked up by whatever the catalog calls it.
+//
+// Two vocabularies name a technology in the catalog and both land here. A
+// store says what it is with a StoreKind - `postgres`, `redis` - and a service
+// carries the names an extractor read off its manifests - `Go`, `Kafka`,
+// `PostgreSQL`. Tomorrow's extractor will spell the same brand a third way,
+// so the table is not keyed by a spelling: every mark lists the names it is
+// known by, and a lookup folds case and punctuation before it compares, so
+// `Postgres`, `postgresql`, `PostgreSQL` and `pg` are one entry.
+//
+// The glyphs come from simple-icons: one filled path per brand, drawn on a
+// 24x24 box. They are painted from currentColor like every other icon in the
+// app, never in the brand's own colour - a red Redis mark beside a grey
+// database glyph would say Redis is the loudest thing on the row, and the row's
+// loudest thing is the event. See ../components/TechIcon for how one is drawn.
+//
+// The table is deliberately wider than what any extractor writes today. A new
+// stack lands as a new marker name in an extractor, and the mark for it should
+// already be here rather than be one more thing that PR has to remember. What
+// is NOT here is anything simple-icons does not carry - S3, gRPC, Protobuf,
+// River, Watermill - because a made-up glyph is a lie about what the brand
+// looks like. Those stay a word, which is what they were before.
+
+import {
+  siAngular,
+  siAnsible,
+  siApachecassandra,
+  siApachecouchdb,
+  siApachekafka,
+  siApachepulsar,
+  siArgo,
+  siAuth0,
+  siBun,
+  siC,
+  siCelery,
+  siCilium,
+  siClickhouse,
+  siClojure,
+  siCloudflare,
+  siCockroachlabs,
+  siConsul,
+  siCouchbase,
+  siCplusplus,
+  siCypress,
+  siDart,
+  siDatadog,
+  siDeno,
+  siDjango,
+  siDocker,
+  siDotnet,
+  siDrizzle,
+  siDuckdb,
+  siElasticsearch,
+  siElectron,
+  siElixir,
+  siEnvoyproxy,
+  siErlang,
+  siEtcd,
+  siExpress,
+  siFastapi,
+  siFastify,
+  siFirebase,
+  siFlask,
+  siFlutter,
+  siGin,
+  siGit,
+  siGithubactions,
+  siGitlab,
+  siGo,
+  siGooglebigquery,
+  siGooglecloud,
+  siGooglecloudspanner,
+  siGradle,
+  siGrafana,
+  siGraphql,
+  siHaskell,
+  siHelm,
+  siHibernate,
+  siHono,
+  siHuggingface,
+  siInfluxdb,
+  siIstio,
+  siJaeger,
+  siJavascript,
+  siJenkins,
+  siJest,
+  siKeycloak,
+  siKotlin,
+  siKtor,
+  siKubernetes,
+  siLangchain,
+  siLaravel,
+  siLinkerd,
+  siLua,
+  siMariadb,
+  siMeilisearch,
+  siMinio,
+  siMongodb,
+  siMqtt,
+  siMysql,
+  siNatsdotio,
+  siNeo4j,
+  siNeon,
+  siNestjs,
+  siNetlify,
+  siNextdotjs,
+  siNginx,
+  siNodedotjs,
+  siNomad,
+  siNpm,
+  siOllama,
+  siOpenapiinitiative,
+  siOpenjdk,
+  siOpensearch,
+  siOpentelemetry,
+  siPhoenixframework,
+  siPhp,
+  siPlanetscale,
+  siPnpm,
+  siPoetry,
+  siPostgresql,
+  siPrisma,
+  siPrometheus,
+  siPulumi,
+  siPytest,
+  siPython,
+  siPytorch,
+  siQuarkus,
+  siRabbitmq,
+  siReact,
+  siRedis,
+  siRuby,
+  siRubyonrails,
+  siRust,
+  siScala,
+  siScylladb,
+  siSentry,
+  siSequelize,
+  siSnowflake,
+  siSpring,
+  siSpringboot,
+  siSqlalchemy,
+  siSqlite,
+  siStripe,
+  siSupabase,
+  siSvelte,
+  siSwift,
+  siSymfony,
+  siTailwindcss,
+  siTauri,
+  siTemporal,
+  siTensorflow,
+  siTerraform,
+  siTidb,
+  siTimescale,
+  siTraefikproxy,
+  siTurso,
+  siTypeorm,
+  siTypescript,
+  siUv,
+  siVault,
+  siVercel,
+  siVictoriametrics,
+  siVite,
+  siVitess,
+  siVitest,
+  siVuedotjs,
+  siWebassembly,
+  siWebpack,
+  siYarn,
+  siZig,
+} from "simple-icons";
+import type { StoreKind } from "../catalog";
+
+export interface TechGlyph {
+  /** The brand's own name, for a title attribute. */
+  title: string;
+  /** SVG path data on a 24x24 box, filled. */
+  path: string;
+}
+
+/** One brand: its glyph and every name it answers to. */
+export interface TechMark extends TechGlyph {
+  /** The brand's title plus its aliases, as written; folded by `techKey`. */
+  names: readonly string[];
+}
+
+/**
+ * How a name is compared: case dropped, everything that is not a letter, a
+ * digit, `+` or `#` dropped. "Node.js" and "nodejs" and "NodeJS" are one key;
+ * "C++" and "C#" keep the characters that make them a different language
+ * from "C".
+ */
+export function techKey(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9+#]/g, "");
+}
+
+function mark(
+  icon: { title: string; path: string },
+  ...aliases: string[]
+): TechMark {
+  return { title: icon.title, path: icon.path, names: [icon.title, ...aliases] };
+}
+
+/**
+ * Every mark the app can draw, grouped the way a reader would list a stack.
+ * Aliases are the spellings an extractor, a manifest or a person is likely to
+ * use; the brand's own title is always one of them.
+ */
+export const TECH_MARKS: readonly TechMark[] = [
+  // Languages and runtimes.
+  mark(siGo, "golang"),
+  mark(siTypescript, "ts"),
+  mark(siJavascript, "js"),
+  mark(siNodedotjs, "node"),
+  mark(siDeno),
+  mark(siBun),
+  mark(siRust),
+  // simple-icons dropped Oracle's Java cup; OpenJDK's is the mark the language
+  // is known by everywhere the trademark is not.
+  mark(siOpenjdk, "Java", "JDK", "JVM"),
+  mark(siKotlin),
+  mark(siScala),
+  mark(siPython),
+  mark(siRuby),
+  mark(siPhp),
+  mark(siC),
+  mark(siCplusplus, "cpp"),
+  mark(siDotnet, "dotnet", "C#", "csharp", "ASP.NET"),
+  mark(siSwift),
+  mark(siDart),
+  mark(siElixir),
+  mark(siErlang),
+  mark(siHaskell),
+  mark(siClojure),
+  mark(siLua),
+  mark(siZig),
+  mark(siWebassembly, "wasm"),
+
+  // Frameworks and libraries.
+  mark(siGin, "gin-gonic"),
+  mark(siDjango),
+  mark(siFastapi),
+  mark(siFlask),
+  mark(siCelery),
+  mark(siSpring),
+  mark(siSpringboot),
+  mark(siQuarkus),
+  mark(siKtor),
+  mark(siRubyonrails, "Rails"),
+  mark(siLaravel),
+  mark(siSymfony),
+  mark(siPhoenixframework, "Phoenix"),
+  mark(siNestjs),
+  mark(siExpress, "expressjs"),
+  mark(siFastify),
+  mark(siHono),
+  mark(siNextdotjs, "nextjs"),
+  mark(siReact),
+  mark(siVuedotjs, "vue"),
+  mark(siAngular),
+  mark(siSvelte, "SvelteKit"),
+  mark(siFlutter),
+  mark(siElectron),
+  mark(siTauri),
+  mark(siGraphql),
+  mark(siOpenapiinitiative, "OpenAPI", "Swagger"),
+  mark(siTemporal),
+  mark(siLangchain),
+  mark(siPytorch),
+  mark(siTensorflow),
+  mark(siOllama),
+  mark(siHuggingface),
+
+  // ORMs and data access.
+  mark(siPrisma),
+  mark(siSqlalchemy),
+  mark(siHibernate),
+  mark(siDrizzle, "Drizzle ORM"),
+  mark(siTypeorm),
+  mark(siSequelize),
+
+  // Stores.
+  mark(siPostgresql, "Postgres", "pg", "psql"),
+  mark(siMysql),
+  mark(siMariadb),
+  mark(siSqlite),
+  mark(siRedis),
+  mark(siMongodb, "Mongo"),
+  mark(siClickhouse),
+  mark(siApachecassandra, "Cassandra"),
+  mark(siScylladb, "Scylla"),
+  mark(siElasticsearch, "Elastic"),
+  mark(siOpensearch),
+  mark(siCockroachlabs, "CockroachDB", "Cockroach"),
+  mark(siTidb),
+  mark(siVitess),
+  mark(siNeo4j),
+  mark(siInfluxdb),
+  mark(siTimescale, "TimescaleDB"),
+  mark(siCouchbase),
+  mark(siApachecouchdb, "CouchDB"),
+  mark(siEtcd),
+  mark(siMinio),
+  mark(siSupabase),
+  mark(siFirebase, "Firestore"),
+  mark(siDuckdb),
+  mark(siSnowflake),
+  mark(siGooglebigquery, "BigQuery"),
+  mark(siGooglecloudspanner, "Spanner"),
+  mark(siMeilisearch),
+  mark(siPlanetscale),
+  mark(siNeon),
+  mark(siTurso),
+
+  // Messaging.
+  mark(siApachekafka, "Kafka"),
+  mark(siNatsdotio, "NATS", "JetStream"),
+  mark(siRabbitmq, "AMQP"),
+  mark(siApachepulsar, "Pulsar"),
+  mark(siMqtt),
+
+  // Infrastructure and delivery.
+  mark(siDocker, "Docker Compose"),
+  mark(siKubernetes, "k8s"),
+  mark(siHelm),
+  mark(siTerraform),
+  mark(siPulumi),
+  mark(siAnsible),
+  mark(siNomad),
+  mark(siConsul),
+  mark(siVault),
+  mark(siNginx),
+  mark(siEnvoyproxy, "Envoy"),
+  mark(siIstio),
+  mark(siLinkerd),
+  mark(siCilium),
+  mark(siTraefikproxy, "Traefik"),
+  mark(siCloudflare),
+  mark(siGooglecloud, "GCP"),
+  mark(siVercel),
+  mark(siNetlify),
+  mark(siGit),
+  mark(siGithubactions),
+  mark(siGitlab, "GitLab CI"),
+  mark(siJenkins),
+  mark(siArgo, "Argo CD", "ArgoCD"),
+
+  // Observability.
+  mark(siOpentelemetry, "otel"),
+  mark(siPrometheus),
+  mark(siGrafana),
+  mark(siJaeger),
+  mark(siVictoriametrics),
+  mark(siSentry),
+  mark(siDatadog),
+
+  // Identity and payments.
+  mark(siKeycloak),
+  mark(siAuth0),
+  mark(siStripe),
+
+  // Build and test tooling.
+  mark(siVite),
+  mark(siWebpack),
+  mark(siTailwindcss, "Tailwind"),
+  mark(siNpm),
+  mark(siPnpm),
+  mark(siYarn),
+  mark(siGradle),
+  mark(siPoetry),
+  mark(siUv),
+  mark(siPytest),
+  mark(siJest),
+  mark(siVitest),
+  mark(siCypress),
+];
+
+const BY_KEY: ReadonlyMap<string, TechGlyph> = (() => {
+  const map = new Map<string, TechGlyph>();
+  for (const { names, title, path } of TECH_MARKS) {
+    const glyph = { title, path };
+    for (const name of names) {
+      map.set(techKey(name), glyph);
+    }
+  }
+  return map;
+})();
+
+/**
+ * The mark for a technology, or null when it is a word only. The name is
+ * folded by `techKey` first, so a caller passes whatever it has.
+ */
+export function techGlyph(name: string): TechGlyph | null {
+  return BY_KEY.get(techKey(name)) ?? null;
+}
+
+/**
+ * Marker names extract-project can write that deliberately have no mark:
+ * simple-icons carries none for them. The test holds every marker in the Go
+ * source to either a glyph or a place here, so a new stack in the extractor
+ * is decided, not forgotten.
+ */
+export const TECH_WITHOUT_GLYPH: readonly string[] = ["River", "Watermill"];
+
+/**
+ * By store kind. `null` is a kind that has no mark, and is listed rather than
+ * left out so that adding a kind to the catalog fails the test until someone
+ * has decided what it looks like.
+ */
+export const STORE_KIND_GLYPH: Record<StoreKind, TechGlyph | null> = {
+  postgres: techGlyph("postgres"),
+  mysql: techGlyph("mysql"),
+  sqlite: techGlyph("sqlite"),
+  redis: techGlyph("redis"),
+  mongodb: techGlyph("mongodb"),
+  clickhouse: techGlyph("clickhouse"),
+  // simple-icons was asked to drop Amazon's marks, S3's among them.
+  s3: null,
+  other: null,
+};

package/src/lib/terms.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../testing/estate";
+import { bindTerms } from "./terms";
+
+const bound = bindTerms(catalog);
+
+const namesOf = (termId: string) =>
+  (bound.byTerm.get(termId) ?? []).map((t) => `${t.kind}:${t.name}`);
+
+describe("bindTerms", () => {
+  it("pairs a word with the aggregate, the entity and the value object it names", () => {
+    expect(namesOf("auth.session")).toContain("entity:Session");
+    expect(namesOf("auth.token")).toContain("vo:Token");
+    // The value object is called email.Address in the code and Email address
+    // in the glossary; the slug is what the two agree on.
+    expect(namesOf("auth.email-address")).toContain("vo:email.Address");
+  });
+
+  it("pairs a word with the command or query that runs it", () => {
+    expect(namesOf("auth.login")).toContain("command:Login");
+    expect(namesOf("auth.validate")).toContain("query:Validate");
+  });
+
+  it("pairs a word with a lifecycle state, which has no page of its own", () => {
+    const locked = bound.byTerm.get("auth.locked") ?? [];
+    const state = locked.find((t) => t.kind === "state");
+
+    expect(state?.name).toBe("locked");
+    expect(state?.path).toMatch(/#bb-lifecycle$/);
+  });
+
+  it("answers from the other end too", () => {
+    const session = catalog.contexts
+      .flatMap((c) => c.services)
+      .flatMap((s) => s.aggregates)
+      .find((a) => a.id === "auth.auth.session");
+    if (!session) throw new Error("fixture has no session aggregate");
+
+    expect(bound.byTarget.get(session.id)?.name).toBe("Session");
+  });
+
+  // The rule is exact, inside one context, and that is the whole rule. A
+  // matcher loose enough to pair Register with registerUser is loose enough to
+  // pair Line with Lineage, and a wrong pairing is worse than none because the
+  // reader believes it.
+  it("says nothing about a word that names nothing", () => {
+    for (const word of ["auth.bus", "auth.outbox", "auth.refusal"]) {
+      expect(bound.byTerm.get(word)).toBeUndefined();
+    }
+  });
+
+  it("never pairs across a context boundary", () => {
+    for (const [termId, targets] of bound.byTerm) {
+      const context = termId.slice(0, termId.indexOf("."));
+      for (const target of targets) {
+        expect(target.id.startsWith(`${context}.`), `${termId} -> ${target.id}`).toBe(true);
+      }
+    }
+  });
+
+  it("is empty for a catalog with no glossary", () => {
+    const bare = bindTerms({ ...catalog, terms: [] });
+
+    expect(bare.byTerm.size).toBe(0);
+    expect(bare.byTarget.size).toBe(0);
+  });
+});