@shortlink-org/portolan 0.1.0

package/src/lib/source-highlight.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { highlightSource } from "./source-highlight";
+
+function classes(value: ReturnType<typeof highlightSource>): string[] {
+  return value.flatMap((node) => {
+    if (node.type === "text") return [];
+    const own = node.properties?.className;
+    return [
+      ...(Array.isArray(own) ? own.filter((item): item is string => typeof item === "string") : []),
+      ...classes(node.children),
+    ];
+  });
+}
+
+describe("highlightSource", () => {
+  it("tokenises a TypeScript source window", () => {
+    const nodes = highlightSource(
+      "basket/handlers.ts",
+      'export const checkout = async (id: string) => "done";',
+    );
+    expect(classes(nodes)).toContain("hljs-keyword");
+    expect(classes(nodes)).toContain("hljs-string");
+  });
+
+  it("keeps unsupported files as plain text", () => {
+    expect(highlightSource("schema/catalog.proto", "message Cart {}"))
+      .toEqual([{ type: "text", value: "message Cart {}" }]);
+  });
+});

package/src/lib/source-highlight.ts

@@ -0,0 +1,24 @@
+import { common, createLowlight } from "lowlight";
+import { sourceGrammar } from "./source-code";
+
+const lowlight = createLowlight(common);
+
+export type HighlightNode =
+  | { type: "text"; value: string }
+  | {
+      type: "element";
+      tagName: string;
+      properties?: Record<string, unknown>;
+      children: HighlightNode[];
+    };
+
+/** Tokenise a bounded source window. Unknown languages deliberately stay plain. */
+export function highlightSource(path: string, code: string): HighlightNode[] {
+  const grammar = sourceGrammar(path);
+  if (!grammar) return [{ type: "text", value: code }];
+  try {
+    return lowlight.highlight(grammar, code).children as HighlightNode[];
+  } catch {
+    return [{ type: "text", value: code }];
+  }
+}

package/src/lib/source-link.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import type { BuildInfo } from "./build-info";
+import type { RepoPin } from "../catalog";
+import { sourceHref, sourceLocation, splitLine, treeHref } from "./source-link";
+
+const GH: BuildInfo = {
+  commit: "4f1c9ae0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
+  shortCommit: "4f1c9ae",
+  branch: "main",
+  builtAt: "",
+  commitUrl: "",
+  buildUrl: "",
+  buildNumber: "",
+  dirty: false,
+  repoUrl: "https://github.com/shortlink-org/portolan",
+};
+
+describe("splitLine", () => {
+  it("takes the line off a file:line", () => {
+    expect(splitLine("internal/oms/app/checkout.go:104")).toEqual({
+      path: "internal/oms/app/checkout.go",
+      line: 104,
+    });
+  });
+  it("leaves anything else whole", () => {
+    expect(splitLine("trace 9f2c1a../span 04")).toEqual({ path: "trace 9f2c1a../span 04", line: null });
+    expect(splitLine("services/oms/test/e2e/checkout_test.go").line).toBeNull();
+  });
+});
+
+const shop = { repo: "github.com/acme/shop" };
+
+const PINS: RepoPin[] = [
+  { repo: "github.com/acme/shop", commit: "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0" },
+];
+
+describe("sourceHref", () => {
+  const auth = { repo: "github.com/shortlink-org/portolan" };
+
+  it("links a file at the built commit, on the line", () => {
+    expect(sourceHref("examples/auth/internal/x.go:20", auth, [], GH)).toBe(
+      "https://github.com/shortlink-org/portolan/blob/4f1c9ae0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6/examples/auth/internal/x.go#L20",
+    );
+    expect(sourceHref("examples/auth/README.md", auth, [], GH)).toMatch(/README\.md$/);
+  });
+
+  it("uses GitLab's /-/blob/ when that is the forge", () => {
+    const gl = { ...GH, repoUrl: "https://gitlab.com/acme/portolan" };
+    expect(sourceHref("a/b.go:1", { repo: "gitlab.com/acme/portolan" }, [], gl)).toBe(
+      "https://gitlab.com/acme/portolan/-/blob/4f1c9ae0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6/a/b.go#L1",
+    );
+  });
+
+  it("does not link a service that lives in another repository, unpinned", () => {
+    expect(sourceHref("internal/oms/app/checkout.go:104", { repo: "github.com/acme/shop" }, [], GH)).toBeNull();
+  });
+
+  it("links a service in another repository at the commit it was fetched at", () => {
+    expect(sourceHref("services/oms/app/checkout.go:104", shop, PINS, GH)).toBe(
+      "https://github.com/acme/shop/blob/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0/services/oms/app/checkout.go#L104",
+    );
+  });
+
+  it("removes the local vendoring prefix from an external source", () => {
+    expect(sourceHref("vendor/repos/acme/shop/services/oms/app/checkout.go:104", shop, PINS, GH)).toBe(
+      "https://github.com/acme/shop/blob/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0/services/oms/app/checkout.go#L104",
+    );
+  });
+
+  it("reads a pin however the repository was spelled", () => {
+    const pins: RepoPin[] = [{ repo: "https://GitHub.com/acme/shop.git", commit: "abc1234" }];
+    expect(sourceHref("services/oms/app/checkout.go", shop, pins, GH)).toBe(
+      "https://github.com/acme/shop/blob/abc1234/services/oms/app/checkout.go",
+    );
+  });
+
+  it("prefers the build over a pin naming the repository this was built from", () => {
+    const pins: RepoPin[] = [{ repo: "github.com/shortlink-org/portolan", commit: "0000000" }];
+    expect(sourceHref("examples/auth/internal/x.go:20", auth, pins, GH)).toContain(GH.commit);
+  });
+
+  it("does not link a pin with no commit", () => {
+    expect(sourceHref("services/oms/app/checkout.go", shop, [{ repo: "github.com/acme/shop", commit: "" }], GH)).toBeNull();
+  });
+
+  it("does not link when the build does not know its repository", () => {
+    expect(sourceHref("examples/auth/internal/x.go:20", auth, [], { ...GH, repoUrl: "" })).toBeNull();
+  });
+
+  it("does not link a place that is not a path", () => {
+    expect(sourceHref("trace 9f2c1a../span 04", auth, [], GH)).toBeNull();
+  });
+
+  it("links a service that names no repository, since there is only the one", () => {
+    expect(sourceHref("docs/x.md", { repo: "" }, [], GH)).toMatch(/\/docs\/x\.md$/);
+  });
+});
+
+describe("sourceLocation", () => {
+  it("keeps the immutable repository, commit, path, and line needed by a preview", () => {
+    expect(sourceLocation("examples/auth/internal/x.go:20", { repo: "github.com/shortlink-org/portolan" }, [], GH)).toEqual({
+      kind: "remote",
+      provider: "github",
+      origin: "https://github.com",
+      repositoryUrl: "https://github.com/shortlink-org/portolan",
+      ref: GH.commit,
+      path: "examples/auth/internal/x.go",
+      line: 20,
+      href: `https://github.com/shortlink-org/portolan/blob/${GH.commit}/examples/auth/internal/x.go#L20`,
+    });
+  });
+
+  it("uses the explicit forge hint for a self-hosted GitLab repository", () => {
+    const gl = { ...GH, repoUrl: "https://git.example.test/acme/portolan", forge: "gitlab" as const };
+    expect(sourceLocation("internal/x.go:3", { repo: "git.example.test/acme/portolan" }, [], gl)).toMatchObject({
+      kind: "remote",
+      provider: "gitlab",
+      origin: "https://git.example.test",
+      ref: GH.commit,
+      path: "internal/x.go",
+      line: 3,
+    });
+  });
+
+  it("falls back to the localhost source service when no forge is known", () => {
+    expect(sourceLocation("internal/x.go:3", null, [], { ...GH, repoUrl: "", commit: "" })).toEqual({
+      kind: "local",
+      path: "internal/x.go",
+      line: 3,
+      href: null,
+    });
+  });
+});
+
+describe("treeHref", () => {
+  it("opens the service's directory", () => {
+    expect(treeHref("examples/auth", { repo: "github.com/shortlink-org/portolan" }, [], GH)).toBe(
+      "https://github.com/shortlink-org/portolan/tree/4f1c9ae0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6/examples/auth",
+    );
+  });
+
+  it("opens a vendored service's directory in the repository it came from", () => {
+    expect(treeHref("services/oms", shop, PINS, GH)).toBe(
+      "https://github.com/acme/shop/tree/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0/services/oms",
+    );
+  });
+
+  it("removes the local vendoring prefix from an external tree", () => {
+    expect(treeHref("vendor/repos/acme/shop/services/oms", shop, PINS, GH)).toBe(
+      "https://github.com/acme/shop/tree/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0/services/oms",
+    );
+  });
+});

package/src/lib/source-link.ts

@@ -0,0 +1,201 @@
+// Where a path in the catalog can be opened.
+//
+// The catalog spells sources three ways: a file, `internal/oms/app/checkout.go`;
+// a file and a line, `order_repo.go:141`; and wherever else a hop was seen,
+// `trace 9f2c1a../span 04`. Only the first two are places on a forge, and only
+// when the forge is known.
+//
+// Two things can know it. The build stamp knows which repository this bundle
+// was built from, which answers for every service that lives here. A repo pin
+// answers for the rest: a service fetched out of another repository is on disk
+// at one commit, and the pin is that commit carried into the catalog - without
+// it, every source path of every vendored service is dead text, which is most
+// of the point of vendoring it undone.
+//
+// When neither knows, the path stays what it was - text to copy - because a
+// link that 404s is worse than none. Guessing `HEAD` of a repository nobody
+// pinned is exactly that guess: the line number would be read against whatever
+// the branch says today, which is a different file from the one the catalog
+// was built from.
+
+import type { RepoPin, Service } from "../catalog";
+import { buildInfo } from "./build-info";
+import type { BuildInfo } from "./build-info";
+
+/** A `file:line` split, or the whole thing as a path when it is not one. */
+export function splitLine(where: string): { path: string; line: number | null } {
+  const m = /^(\S+?):(\d+)$/.exec(where);
+  if (m) return { path: m[1]!, line: Number(m[2]) };
+  return { path: where, line: null };
+}
+
+/** Whether a string is shaped like a path in a tree, not a sentence. */
+export function looksLikePath(path: string): boolean {
+  // A dot or a slash is what separates `Makefile:3` and `cmd/main.go` from a
+  // word somebody wrote where a path was expected; a bare `Makefile` at the
+  // root of a repository is a path all the same.
+  return (
+    /^[\w./@+-]+$/.test(path) &&
+    !path.startsWith("/") &&
+    (path.includes(".") || path.includes("/") || /file$/i.test(path))
+  );
+}
+
+/**
+ * Whether `repo` is the repository this bundle was built from.
+ *
+ * `repo` is written the way go.mod writes it, `github.com/org/name`; the build
+ * stamp has the same thing with a scheme. An empty `repo` is a source that
+ * names no service - a hand-written flow, a glossary term - and belongs to
+ * whatever this was built from.
+ */
+function sameRepo(repo: string, info: BuildInfo): boolean {
+  if (!info.repoUrl) return false;
+  if (!repo) return true;
+
+  return bare(info.repoUrl) === bare(repo);
+}
+
+/** A repository as `host/owner/name`, however it was spelled. */
+export function bare(repo: string): string {
+  return repo
+    .replace(/^https?:\/\//, "")
+    .replace(/\.git$/, "")
+    .replace(/\/$/, "")
+    .toLowerCase();
+}
+
+/** Translate a path in the committed vendor copy back to the remote tree. */
+function repositoryPath(path: string, repo: string, info: BuildInfo): string {
+  if (!repo || sameRepo(repo, info)) return path;
+  const segments = bare(repo).split("/").filter(Boolean);
+  if (segments.length < 3) return path;
+  const prefix = `vendor/repos/${segments.at(-2)}/${segments.at(-1)}/`;
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+
+/** GitLab keeps the tree under /-/; everything else uses /blob directly. */
+function blobPath(url: string): string {
+  return /gitlab/i.test(url) ? "/-/blob/" : "/blob/";
+}
+
+/** The repository a service's paths are read against, and the commit to read them at. */
+interface Where {
+  url: string;
+  ref: string;
+}
+
+export type RemoteSourceLocation = {
+  kind: "remote";
+  provider: "github" | "gitlab";
+  origin: string;
+  repositoryUrl: string;
+  ref: string;
+  path: string;
+  line: number | null;
+  href: string;
+};
+
+export type LocalSourceLocation = {
+  kind: "local";
+  path: string;
+  line: number | null;
+  href: string | null;
+};
+
+/** Everything needed to fetch and display the immutable source behind a catalog fact. */
+export type SourceLocation = RemoteSourceLocation | LocalSourceLocation;
+
+/**
+ * Where `service` can be read: this repository at the built commit, or the
+ * repository the service lives in at the commit it was fetched at. Null when
+ * neither is known, which is the answer a link is not built from.
+ */
+function whereFor(
+  repo: string,
+  pins: readonly RepoPin[],
+  info: BuildInfo,
+): Where | null {
+  if (sameRepo(repo, info)) {
+    return { url: info.repoUrl.replace(/\/$/, ""), ref: info.commit || "HEAD" };
+  }
+
+  const pin = pins.find((p) => bare(p.repo) === bare(repo));
+  if (!pin || !pin.commit) return null;
+
+  return { url: `https://${bare(pin.repo)}`, ref: pin.commit };
+}
+
+function providerFor(url: string, info: BuildInfo): "github" | "gitlab" | null {
+  let host = "";
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  if (info.repoUrl && bare(info.repoUrl) === bare(url) && info.forge) return info.forge;
+  if (host === "github.com" || host.endsWith(".github.com")) return "github";
+  if (host === "gitlab.com" || host.includes("gitlab")) return "gitlab";
+  return null;
+}
+
+/**
+ * Resolve a catalog source to a fetchable location. When no forge is known,
+ * the same relative path can still be served by Portolan's localhost-only
+ * control plane in local mode.
+ */
+export function sourceLocation(
+  where: string,
+  service: Pick<Service, "repo"> | null | undefined,
+  pins: readonly RepoPin[] = [],
+  info: BuildInfo = buildInfo,
+): SourceLocation | null {
+  const { path, line } = splitLine(where);
+  if (!looksLikePath(path)) return null;
+  const repo = service?.repo ?? "";
+  const at = whereFor(repo, pins, info);
+  const href = at
+    ? `${at.url}${blobPath(at.url)}${at.ref}/${repositoryPath(path, repo, info)}${line ? `#L${line}` : ""}`
+    : null;
+  if (!at) return { kind: "local", path, line, href: null };
+
+  const provider = providerFor(at.url, info);
+  if (!provider) return { kind: "local", path, line, href };
+  return {
+    kind: "remote",
+    provider,
+    origin: new URL(at.url).origin,
+    repositoryUrl: at.url,
+    ref: at.ref,
+    path: repositoryPath(path, repo, info),
+    line,
+    href: href!,
+  };
+}
+
+/**
+ * A link to `where` in the repository `service` lives in, or null when the
+ * path is not one, or nothing knows where that repository is.
+ */
+export function sourceHref(
+  where: string,
+  service: Pick<Service, "repo"> | null | undefined,
+  pins: readonly RepoPin[] = [],
+  info: BuildInfo = buildInfo,
+): string | null {
+  return sourceLocation(where, service, pins, info)?.href ?? null;
+}
+
+/** A link to a directory of the repository, for a service's own path. */
+export function treeHref(
+  path: string,
+  service: Pick<Service, "repo"> | null | undefined,
+  pins: readonly RepoPin[] = [],
+  info: BuildInfo = buildInfo,
+): string | null {
+  if (!path) return null;
+  const at = whereFor(service?.repo ?? "", pins, info);
+  if (!at) return null;
+
+  return `${at.url}${blobPath(at.url).replace("blob", "tree")}${at.ref}/${repositoryPath(path.replace(/\/$/, ""), service?.repo ?? "", info)}`;
+}

package/src/lib/spec-files.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { loaderFor } from "./spec-files";
+
+const load = async () => "openapi: 3.0.3";
+
+describe("loaderFor", () => {
+  it("matches a catalog source against a glob key", () => {
+    const specs = { "../../examples/auth/openapi.yaml": load };
+
+    expect(loaderFor(specs, "examples/auth/openapi.yaml")).toBe(load);
+  });
+
+  it("answers nothing for a document this repository does not hold", () => {
+    const specs = { "../../examples/auth/openapi.yaml": load };
+
+    expect(loaderFor(specs, "examples/billing/openapi.yaml")).toBeNull();
+  });
+
+  // A document in another repository is the normal case for a real estate, and
+  // an empty glob is what that looks like here.
+  it("answers nothing when the repository holds none at all", () => {
+    expect(loaderFor({}, "examples/auth/openapi.yaml")).toBeNull();
+  });
+});

package/src/lib/spec-files.ts

@@ -0,0 +1,23 @@
+// Which source documents this repository actually holds.
+//
+// `import.meta.glob` needs a literal pattern, so the glob itself stays in the
+// component that draws the document - one for OpenAPI, one for AsyncAPI - and
+// this is what both of them do with the answer.
+//
+// A catalog source is a path as the extractor wrote it, relative to the
+// repository root; a glob's keys are relative to the file the glob is written
+// in. Stripping the leading `../` is what makes the two comparable, and it is
+// the whole of the trick.
+
+export type Specs = Record<string, () => Promise<string>>;
+
+export function loaderFor(
+  specs: Specs,
+  source: string,
+): (() => Promise<string>) | null {
+  for (const [path, load] of Object.entries(specs)) {
+    if (path.replace(/^(\.\.\/)+/, "") === source) return load;
+  }
+
+  return null;
+}

package/src/lib/table-directive.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import {
+  TABLE_DIRECTIVE_ATTR,
+  columnSlug,
+  parseTableComment,
+  parseTableDirective,
+  remarkTableDirective,
+} from "./table-directive";
+
+describe("parseTableComment", () => {
+  it("reads the body of a table comment", () => {
+    expect(parseTableComment("<!-- table: static -->")).toBe("static");
+  });
+
+  it("tolerates the spacing an author actually types", () => {
+    expect(parseTableComment("<!--table:static-->")).toBe("static");
+    expect(parseTableComment("  <!--   table:   static   -->  ")).toBe("static");
+  });
+
+  it("leaves an ordinary comment alone", () => {
+    expect(parseTableComment("<!-- prettier-ignore -->")).toBeNull();
+  });
+
+  it("reads an empty directive as empty, not as absent", () => {
+    expect(parseTableComment("<!-- table: -->")).toBe("");
+  });
+});
+
+describe("parseTableDirective", () => {
+  it("reads static", () => {
+    expect(parseTableDirective("static")).toEqual({ static: true, sort: null });
+  });
+
+  it("reads a default sort", () => {
+    expect(parseTableDirective("sort=name.desc")).toEqual({
+      static: false,
+      sort: { id: "name", desc: true },
+    });
+  });
+
+  it("reads both at once", () => {
+    expect(parseTableDirective("static sort=name.asc")).toEqual({
+      static: true,
+      sort: { id: "name", desc: false },
+    });
+  });
+
+  it("keeps a column id containing a dot", () => {
+    expect(parseTableDirective("sort=a.b.desc").sort).toEqual({
+      id: "a.b",
+      desc: true,
+    });
+  });
+
+  it("ignores a word it does not know", () => {
+    expect(parseTableDirective("sideways sort=a.asc")).toEqual({
+      static: false,
+      sort: { id: "a", desc: false },
+    });
+  });
+
+  it("ignores a direction that is not one", () => {
+    expect(parseTableDirective("sort=a.sideways").sort).toBeNull();
+  });
+});
+
+describe("columnSlug", () => {
+  it("slugs a header", () => {
+    expect(columnSlug("Last seen", new Set())).toBe("last-seen");
+  });
+
+  it("numbers a repeat rather than colliding", () => {
+    const taken = new Set(["name"]);
+    expect(columnSlug("name", taken)).toBe("name-2");
+  });
+
+  it("falls back for a header with nothing sluggable in it", () => {
+    expect(columnSlug("—", new Set())).toBe("col");
+  });
+});
+
+describe("remarkTableDirective", () => {
+  const run = (tree: unknown) => {
+    remarkTableDirective()(tree as never);
+    return tree as { children: { data?: { hProperties?: Record<string, string> } }[] };
+  };
+
+  it("attaches the comment above a table to it", () => {
+    const tree = run({
+      type: "root",
+      children: [
+        { type: "html", value: "<!-- table: static -->" },
+        { type: "table", children: [] },
+      ],
+    });
+    expect(tree.children[1]?.data?.hProperties).toEqual({
+      [TABLE_DIRECTIVE_ATTR]: "static",
+    });
+  });
+
+  it("leaves a table with nothing above it alone", () => {
+    const tree = run({ type: "root", children: [{ type: "table", children: [] }] });
+    expect(tree.children[0]?.data).toBeUndefined();
+  });
+
+  it("ignores a comment separated from the table by a paragraph", () => {
+    const tree = run({
+      type: "root",
+      children: [
+        { type: "html", value: "<!-- table: static -->" },
+        { type: "paragraph", children: [] },
+        { type: "table", children: [] },
+      ],
+    });
+    expect(tree.children[2]?.data).toBeUndefined();
+  });
+
+  it("reaches a table nested inside a blockquote", () => {
+    const tree = run({
+      type: "root",
+      children: [
+        {
+          type: "blockquote",
+          children: [
+            { type: "html", value: "<!-- table: sort=n.desc -->" },
+            { type: "table", children: [] },
+          ],
+        },
+      ],
+    }) as never as {
+      children: {
+        children: { data?: { hProperties?: Record<string, string> } }[];
+      }[];
+    };
+    expect(tree.children[0]?.children[1]?.data?.hProperties).toEqual({
+      [TABLE_DIRECTIVE_ATTR]: "sort=n.desc",
+    });
+  });
+});