@shortlink-org/portolan 0.1.0

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

@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  loadSourceCode,
+  sourceLanguage,
+  sourceGrammar,
+  sourceWindow,
+  SourceLoadError,
+} from "./source-code";
+import type { RemoteSourceLocation, SourceLocation } from "./source-link";
+
+const github: RemoteSourceLocation = {
+  kind: "remote",
+  provider: "github",
+  origin: "https://github.com",
+  repositoryUrl: "https://github.com/acme/shop",
+  ref: "a".repeat(40),
+  path: "internal/cart/cart.go",
+  line: 3,
+  href: "https://github.com/acme/shop/blob/a/internal/cart/cart.go#L3",
+};
+
+const gitlab: RemoteSourceLocation = {
+  ...github,
+  provider: "gitlab",
+  origin: "https://gitlab.example.test",
+  repositoryUrl: "https://gitlab.example.test/platform/acme/shop",
+  href: "https://gitlab.example.test/platform/acme/shop/-/blob/a/internal/cart/cart.go#L3",
+};
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("loadSourceCode", () => {
+  it("loads GitHub contents at the catalog commit with a bearer token", async () => {
+    const fetch = vi
+      .fn()
+      .mockResolvedValue(new Response("package cart\n", { status: 200 }));
+    vi.stubGlobal("fetch", fetch);
+    await expect(loadSourceCode(github, "secret")).resolves.toMatchObject({
+      content: "package cart\n",
+      path: github.path,
+      ref: github.ref,
+    });
+    const [url, init] = fetch.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain(
+      `/repos/acme/shop/contents/internal/cart/cart.go?ref=${github.ref}`,
+    );
+    expect(init.headers).toMatchObject({ Authorization: "Bearer secret" });
+    expect(init.cache).toBe("no-store");
+  });
+
+  it("loads nested GitLab projects with PRIVATE-TOKEN", async () => {
+    const fetch = vi
+      .fn()
+      .mockResolvedValue(new Response("package cart\n", { status: 200 }));
+    vi.stubGlobal("fetch", fetch);
+    await loadSourceCode(gitlab, "private");
+    const [url, init] = fetch.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain(
+      "/api/v4/projects/platform%2Facme%2Fshop/repository/files/internal%2Fcart%2Fcart.go/raw",
+    );
+    expect(init.headers).toEqual({ "PRIVATE-TOKEN": "private" });
+  });
+
+  it("classifies an anonymous 404 as possible private-repository access", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(new Response("", { status: 404 })),
+    );
+    const error = await loadSourceCode(github).catch((cause: unknown) => cause);
+    expect(error).toBeInstanceOf(SourceLoadError);
+    expect(error).toMatchObject({ status: 404, authRequired: true });
+  });
+
+  it("asks the forge every time; remembering the answer is the query layer's job", async () => {
+    const fetch = vi
+      .fn()
+      .mockResolvedValueOnce(new Response("", { status: 404 }))
+      .mockImplementation(async () => new Response("ok\n", { status: 200 }));
+    vi.stubGlobal("fetch", fetch);
+    await expect(loadSourceCode(github)).rejects.toBeInstanceOf(
+      SourceLoadError,
+    );
+    await loadSourceCode(github, "token");
+    await loadSourceCode(github, "token");
+    expect(fetch).toHaveBeenCalledTimes(3);
+  });
+
+  it("uses the localhost-only endpoint for a local source", async () => {
+    const local: SourceLocation = {
+      kind: "local",
+      path: "internal/cart/cart.go",
+      line: 1,
+      href: null,
+    };
+    const fetch = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({ path: local.path, content: "package cart\n" }),
+        {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        },
+      ),
+    );
+    vi.stubGlobal("fetch", fetch);
+    await expect(loadSourceCode(local)).resolves.toMatchObject({
+      content: "package cart\n",
+      ref: "working tree",
+    });
+    expect(fetch).toHaveBeenCalledWith(
+      "/__portolan/source",
+      expect.objectContaining({ method: "POST", cache: "no-store" }),
+    );
+  });
+
+  it("rejects binary and oversized remote files", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockResolvedValue(
+          new Response(new Uint8Array([1, 0, 2]), { status: 200 }),
+        ),
+    );
+    await expect(loadSourceCode(github)).rejects.toThrow("binary file");
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockResolvedValue(
+          new Response("", {
+            status: 200,
+            headers: { "content-length": "1048577" },
+          }),
+        ),
+    );
+    await expect(loadSourceCode(github)).rejects.toThrow("1 MB preview limit");
+  });
+});
+
+describe("sourceWindow", () => {
+  it("centres a bounded window on the catalog line", () => {
+    const rows = sourceWindow(
+      Array.from({ length: 20 }, (_, index) => `line ${index + 1}`).join("\n"),
+      10,
+      2,
+    );
+    expect(rows.map((row) => row.number)).toEqual([8, 9, 10, 11, 12]);
+    expect(rows.find((row) => row.focused)?.text).toBe("line 10");
+  });
+
+  it("labels common source languages", () => {
+    expect(sourceLanguage("internal/cart/cart.go")).toBe("Go");
+    expect(sourceLanguage("api/provider.wsdl")).toBe("WSDL");
+    expect(sourceLanguage("ui/checkout.tsx")).toBe("TSX");
+    expect(sourceGrammar("ui/checkout.tsx")).toBe("typescript");
+    expect(sourceGrammar("api/provider.wsdl")).toBe("xml");
+    expect(sourceGrammar("schema/catalog.proto")).toBeNull();
+  });
+});

package/src/lib/source-code.ts

@@ -0,0 +1,286 @@
+import type { RemoteSourceLocation, SourceLocation } from "./source-link";
+
+const MAX_SOURCE_BYTES = 1024 * 1024;
+
+export type SourceFile = {
+  content: string;
+  path: string;
+  ref: string;
+};
+
+export type SourceLine = {
+  number: number;
+  text: string;
+  focused: boolean;
+};
+
+export class SourceLoadError extends Error {
+  readonly status: number;
+  readonly authRequired: boolean;
+
+  constructor(message: string, status = 0, authRequired = false) {
+    super(message);
+    this.name = "SourceLoadError";
+    this.status = status;
+    this.authRequired = authRequired;
+  }
+}
+
+function encodedPath(path: string): string {
+  return path.split("/").map(encodeURIComponent).join("/");
+}
+
+function remoteRequest(
+  location: RemoteSourceLocation,
+  token: string,
+): { url: string; headers: HeadersInit } {
+  const repoUrl = new URL(location.repositoryUrl);
+  const parts = repoUrl.pathname.split("/").filter(Boolean);
+  if (parts.length < 2)
+    throw new SourceLoadError("The repository URL is incomplete.");
+
+  if (location.provider === "github") {
+    const owner = parts[0]!;
+    const repo = parts
+      .slice(1)
+      .join("/")
+      .replace(/\.git$/, "");
+    const api =
+      repoUrl.hostname === "github.com"
+        ? "https://api.github.com"
+        : `${repoUrl.origin}/api/v3`;
+    return {
+      url: `${api}/repos/${encodeURIComponent(owner)}/${repo.split("/").map(encodeURIComponent).join("/")}/contents/${encodedPath(location.path)}?ref=${encodeURIComponent(location.ref)}`,
+      headers: {
+        Accept: "application/vnd.github.raw+json",
+        "X-GitHub-Api-Version": "2026-03-10",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+    };
+  }
+
+  const project = parts.join("/").replace(/\.git$/, "");
+  return {
+    url: `${repoUrl.origin}/api/v4/projects/${encodeURIComponent(project)}/repository/files/${encodeURIComponent(location.path)}/raw?ref=${encodeURIComponent(location.ref)}`,
+    headers: token ? { "PRIVATE-TOKEN": token } : {},
+  };
+}
+
+function loadError(
+  location: RemoteSourceLocation,
+  response: Response,
+  token: string,
+): SourceLoadError {
+  const forge = location.provider === "github" ? "GitHub" : "GitLab";
+  const authRequired =
+    response.status === 401 ||
+    response.status === 403 ||
+    (!token && response.status === 404);
+  if (authRequired) {
+    return new SourceLoadError(
+      token
+        ? `${forge} rejected the token or it cannot read this repository.`
+        : `${forge} could not read this file. The repository may be private.`,
+      response.status,
+      true,
+    );
+  }
+  if (response.status === 404) {
+    return new SourceLoadError(
+      "The source file does not exist at this commit.",
+      404,
+    );
+  }
+  if (response.status === 429) {
+    return new SourceLoadError(`${forge} API rate limit reached.`, 429);
+  }
+  return new SourceLoadError(
+    `${forge} could not load the source file (${response.status}).`,
+    response.status,
+  );
+}
+
+async function responseText(
+  response: Response,
+  label: string,
+): Promise<string> {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_SOURCE_BYTES) {
+    throw new SourceLoadError(
+      `${label} is larger than the 1 MB preview limit.`,
+    );
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.byteLength > MAX_SOURCE_BYTES) {
+    throw new SourceLoadError(
+      `${label} is larger than the 1 MB preview limit.`,
+    );
+  }
+  if (bytes.includes(0))
+    throw new SourceLoadError(`${label} is a binary file.`);
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new SourceLoadError(`${label} is not UTF-8 text.`);
+  }
+}
+
+async function loadRemote(
+  location: RemoteSourceLocation,
+  token: string,
+): Promise<SourceFile> {
+  const request = remoteRequest(location, token);
+  const response = await fetch(request.url, {
+    headers: request.headers,
+    cache: token ? "no-store" : "default",
+  });
+  if (!response.ok) throw loadError(location, response, token);
+  return {
+    content: await responseText(response, location.path),
+    path: location.path,
+    ref: location.ref,
+  };
+}
+
+async function loadLocal(
+  location: Extract<SourceLocation, { kind: "local" }>,
+): Promise<SourceFile> {
+  const response = await fetch("/__portolan/source", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-Portolan-Local": "1" },
+    body: JSON.stringify({ path: location.path }),
+    cache: "no-store",
+  });
+  let value: unknown;
+  try {
+    value = await response.json();
+  } catch {
+    throw new SourceLoadError(
+      "Local source preview is available only in Portolan local mode.",
+      response.status,
+    );
+  }
+  if (!response.ok) {
+    const message =
+      typeof value === "object" &&
+      value &&
+      "error" in value &&
+      typeof value.error === "string"
+        ? value.error
+        : `Local source could not be loaded (${response.status}).`;
+    throw new SourceLoadError(message, response.status);
+  }
+  if (
+    typeof value !== "object" ||
+    !value ||
+    !("content" in value) ||
+    typeof value.content !== "string"
+  ) {
+    throw new SourceLoadError("Local source returned an invalid response.");
+  }
+  return { content: value.content, path: location.path, ref: "working tree" };
+}
+
+/**
+ * Load one source file. Nothing is remembered here: the query layer keeps
+ * the answer for the tab, in memory only, so an authenticated file never
+ * reaches Cache Storage.
+ */
+export function loadSourceCode(
+  location: SourceLocation,
+  token = "",
+): Promise<SourceFile> {
+  return location.kind === "remote"
+    ? loadRemote(location, token)
+    : loadLocal(location);
+}
+
+/** The bounded window rendered by the popover, with the catalog line marked. */
+export function sourceWindow(
+  content: string,
+  line: number | null,
+  radius = 15,
+): SourceLine[] {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  const focus = Math.max(1, Math.min(line ?? 1, lines.length));
+  const start = line ? Math.max(1, focus - radius) : 1;
+  const end = line
+    ? Math.min(lines.length, focus + radius)
+    : Math.min(lines.length, radius * 2 + 1);
+  return lines.slice(start - 1, end).map((text, index) => ({
+    number: start + index,
+    text,
+    focused: line !== null && start + index === focus,
+  }));
+}
+
+type SourceLanguageDefinition = { label: string; grammar: string | null };
+
+const SOURCE_LANGUAGES: Record<string, SourceLanguageDefinition> = {
+  go: { label: "Go", grammar: "go" },
+  rs: { label: "Rust", grammar: "rust" },
+  ts: { label: "TypeScript", grammar: "typescript" },
+  tsx: { label: "TSX", grammar: "typescript" },
+  mts: { label: "TypeScript", grammar: "typescript" },
+  cts: { label: "TypeScript", grammar: "typescript" },
+  js: { label: "JavaScript", grammar: "javascript" },
+  jsx: { label: "JSX", grammar: "javascript" },
+  mjs: { label: "JavaScript", grammar: "javascript" },
+  cjs: { label: "JavaScript", grammar: "javascript" },
+  java: { label: "Java", grammar: "java" },
+  py: { label: "Python", grammar: "python" },
+  rb: { label: "Ruby", grammar: "ruby" },
+  php: { label: "PHP", grammar: "php" },
+  cs: { label: "C#", grammar: "csharp" },
+  kt: { label: "Kotlin", grammar: "kotlin" },
+  kts: { label: "Kotlin", grammar: "kotlin" },
+  scala: { label: "Scala", grammar: null },
+  c: { label: "C", grammar: "c" },
+  h: { label: "C", grammar: "c" },
+  cc: { label: "C++", grammar: "cpp" },
+  cpp: { label: "C++", grammar: "cpp" },
+  hpp: { label: "C++", grammar: "cpp" },
+  sql: { label: "SQL", grammar: "sql" },
+  proto: { label: "Protocol Buffers", grammar: null },
+  graphql: { label: "GraphQL", grammar: "graphql" },
+  graphqls: { label: "GraphQL", grammar: "graphql" },
+  yaml: { label: "YAML", grammar: "yaml" },
+  yml: { label: "YAML", grammar: "yaml" },
+  json: { label: "JSON", grammar: "json" },
+  xml: { label: "XML", grammar: "xml" },
+  wsdl: { label: "WSDL", grammar: "xml" },
+  html: { label: "HTML", grammar: "xml" },
+  htm: { label: "HTML", grammar: "xml" },
+  css: { label: "CSS", grammar: "css" },
+  scss: { label: "SCSS", grammar: "scss" },
+  less: { label: "Less", grammar: "less" },
+  md: { label: "Markdown", grammar: "markdown" },
+  markdown: { label: "Markdown", grammar: "markdown" },
+  sh: { label: "Shell", grammar: "bash" },
+  bash: { label: "Shell", grammar: "bash" },
+  zsh: { label: "Shell", grammar: "bash" },
+  lua: { label: "Lua", grammar: "lua" },
+  swift: { label: "Swift", grammar: "swift" },
+  r: { label: "R", grammar: "r" },
+  ini: { label: "INI", grammar: "ini" },
+  toml: { label: "TOML", grammar: "ini" },
+};
+
+function languageDefinition(path: string): SourceLanguageDefinition | null {
+  const filename = path.split("/").at(-1)?.toLowerCase() ?? "";
+  if (filename === "makefile") return { label: "Makefile", grammar: "makefile" };
+  const extension = path.split(".").at(-1)?.toLowerCase() ?? "";
+  return SOURCE_LANGUAGES[extension] ?? null;
+}
+
+export function sourceLanguage(path: string): string {
+  const definition = languageDefinition(path);
+  if (definition) return definition.label;
+  const extension = path.split(".").at(-1)?.toLowerCase() ?? "";
+  return extension ? extension.toUpperCase() : "text";
+}
+
+/** Lowlight grammar name, or null when the file should remain plain text. */
+export function sourceGrammar(path: string): string | null {
+  return languageDefinition(path)?.grammar ?? null;
+}

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

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import type { Service } from "../catalog";
+import { docPathOf, pickSpec, sourceDocKind, sourceLineOf } from "./source-doc";
+
+function service(
+  provides: { id: string; source: string; module?: string }[],
+): Service {
+  return {
+    id: "shop.oms",
+    slug: "oms",
+    name: "oms",
+    repo: "",
+    path: "",
+    readme: "",
+    provides: provides.map((p) => ({ ...p, methods: [] })),
+    consumes: [],
+    aggregates: [],
+  };
+}
+
+describe("docPathOf", () => {
+  // The bug a naive extension check walks straight into: a proto source names
+  // the line its declaration sits on, and an OpenAPI one never did.
+  it("strips the line number a proto source carries", () => {
+    expect(docPathOf("proto/shop/v1/orders.proto:12")).toBe(
+      "proto/shop/v1/orders.proto",
+    );
+  });
+
+  it("leaves a path with no line alone, and is idempotent", () => {
+    const plain = "examples/auth/openapi.yaml";
+    expect(docPathOf(plain)).toBe(plain);
+    expect(docPathOf(docPathOf("a/b.proto:9"))).toBe("a/b.proto");
+  });
+
+  // Only a trailing `:digits` is a line number. Anything else is part of the
+  // path and removing it would name a file that does not exist.
+  it("does not eat a colon that is not a trailing line number", () => {
+    expect(docPathOf("C:/protos/orders.proto")).toBe("C:/protos/orders.proto");
+    expect(docPathOf("a:12/b.proto")).toBe("a:12/b.proto");
+  });
+
+  it("reads the line back out", () => {
+    expect(sourceLineOf("proto/shop/v1/orders.proto:12")).toBe(12);
+    expect(sourceLineOf("examples/auth/openapi.yaml")).toBeNull();
+  });
+});
+
+describe("sourceDocKind", () => {
+  it("tells supported API documents apart, line number and all", () => {
+    expect(sourceDocKind("proto/shop/v1/orders.proto:12")).toBe("proto");
+    expect(sourceDocKind("examples/auth/openapi.yaml")).toBe("openapi");
+    expect(sourceDocKind("examples/auth/openapi.yml")).toBe("openapi");
+    expect(sourceDocKind("vendor/repos/commerce/billing/docs/swagger.json")).toBe(
+      "openapi",
+    );
+    expect(sourceDocKind("examples/bff/src/schema/basket/schema.graphql")).toBe("graphql");
+    expect(sourceDocKind("contracts/booking.wsdl")).toBe("wsdl");
+    expect(sourceDocKind("internal/handler.go")).toBeNull();
+  });
+});
+
+describe("pickSpec", () => {
+  const held = (source: string) => source.endsWith(".yaml");
+
+  it("prefers a document this repository actually holds", () => {
+    const choice = pickSpec(
+      service([
+        { id: "shop.v1.Orders", source: "proto/orders.proto:12", module: "m" },
+        { id: "auth.v1.Users", source: "examples/auth/openapi.yaml" },
+      ]),
+      held,
+    );
+
+    expect(choice).toEqual({
+      kind: "openapi",
+      source: "examples/auth/openapi.yaml",
+    });
+  });
+
+  // A schema is a document this repository holds like any other, and the tab
+  // draws it as written rather than as a second copy of the provides tab.
+  it("picks the graphql schema an interface was read from", () => {
+    expect(
+      pickSpec(
+        service([{ id: "storefront.v1.Basket", source: "examples/bff/src/schema/basket/schema.graphql" }]),
+        (source) => source.endsWith(".graphql"),
+      ),
+    ).toEqual({ kind: "graphql", source: "examples/bff/src/schema/basket/schema.graphql" });
+  });
+
+  it("falls back to the module the interfaces came from", () => {
+    expect(
+      pickSpec(
+        service([
+          {
+            id: "shop.v1.Orders",
+            source: "proto/orders.proto:12",
+            module: "buf.build/acme/shop",
+          },
+        ]),
+        held,
+      ),
+    ).toEqual({ kind: "module", moduleId: "buf.build/acme/shop" });
+  });
+
+  it("draws a WSDL from structured catalog facts without bundling the file", () => {
+    expect(
+      pickSpec(
+        service([{ id: "booking.soap.BookingPort", source: "contracts/booking.wsdl" }]),
+        () => false,
+      ),
+    ).toEqual({ kind: "wsdl", source: "contracts/booking.wsdl" });
+  });
+
+  // A spec in another repository is the normal case for a real estate: the
+  // catalog still lists what the service answers, and the tab says so.
+  it("has nothing to show for an interface with neither", () => {
+    expect(
+      pickSpec(service([{ id: "x", source: "internal/handler.go" }]), held),
+    ).toBeNull();
+    expect(pickSpec(service([]), held)).toBeNull();
+  });
+
+  it("shows an honest inferred contract for HTTP routes read from framework code", () => {
+    const inferred = service([{ id: "avia.aviadmin.http", source: "adminavia/urls.py" }]);
+    inferred.provides[0]!.methods = [{ name: "orders_get", http: { method: "GET", path: "/orders/" } }];
+
+    expect(pickSpec(inferred, () => false)).toEqual({ kind: "inferred-http" });
+  });
+});

package/src/lib/source-doc.ts

@@ -0,0 +1,103 @@
+// Which document a service's interfaces were read out of, and what can be
+// drawn from it.
+//
+// `ApiReference` states the rule this module serves: the source document is
+// drawn because the catalog cannot carry the document's own shape, and
+// re-deriving that into the schema would be rebuilding OpenAPI inside it.
+//
+// For a proto that premise is false. The extractor reads exactly that shape -
+// services, methods, the two messages each one moves - so the catalog already
+// holds it, structured and linkable. Drawing the raw text would be showing a
+// worse copy of data we have: a `<pre>` cannot link a field to the shared type
+// it refs, or a method to the operation it exposes.
+
+import type { Service } from "../catalog";
+
+/**
+ * The path part of a source reference.
+ *
+ * A proto source carries the line the declaration sits on -
+ * `proto/shop/v1/orders.proto:12` - and an OpenAPI one does not, which is why
+ * `hasSpec` never had to care. Checking the extension against the raw string
+ * would classify every proto as unknown.
+ */
+export function docPathOf(source: string): string {
+  return source.replace(/:\d+$/, "");
+}
+
+/** The line a declaration sits on, when the source names one. */
+export function sourceLineOf(source: string): number | null {
+  const at = /:(\d+)$/.exec(source);
+
+  return at?.[1] ? Number(at[1]) : null;
+}
+
+export type SourceDocKind = "openapi" | "proto" | "graphql" | "wsdl" | null;
+
+export function sourceDocKind(source: string): SourceDocKind {
+  const path = docPathOf(source).toLowerCase();
+  if (path.endsWith(".proto")) return "proto";
+  if (path.endsWith(".wsdl")) return "wsdl";
+  if (path.endsWith(".graphql") || path.endsWith(".graphqls")) return "graphql";
+  if (
+    path.endsWith(".yaml") ||
+    path.endsWith(".yml") ||
+    path.endsWith(".json")
+  ) {
+    return "openapi";
+  }
+
+  return null;
+}
+
+/** What the spec tab should draw. */
+export type SpecChoice =
+  | { kind: "openapi"; source: string }
+  | { kind: "graphql"; source: string }
+  | { kind: "wsdl"; source: string }
+  | { kind: "module"; moduleId: string }
+  | { kind: "inferred-http" };
+
+/**
+ * The document to show for a service.
+ *
+ * Precedence: an OpenAPI/GraphQL document this repository actually holds,
+ * then a structured WSDL, then the module its interfaces came from. The
+ * predicate is injected so the globs stay in the component layer and this
+ * stays testable without a bundler.
+ */
+export function pickSpec(
+  service: Service,
+  hasDocument: (source: string) => boolean,
+): SpecChoice | null {
+  for (const provided of service.provides) {
+    const kind = sourceDocKind(provided.source);
+    if (!hasDocument(provided.source)) continue;
+    if (kind === "openapi" || kind === "graphql") {
+      return { kind, source: provided.source };
+    }
+  }
+
+  // A WSDL is fully represented by the catalog: operations, bindings,
+  // request/response messages and XSD shapes. It remains drawable even when
+  // the source checkout is not bundled into this site.
+  for (const provided of service.provides) {
+    if (sourceDocKind(provided.source) === "wsdl") {
+      return { kind: "wsdl", source: provided.source };
+    }
+  }
+
+  for (const provided of service.provides) {
+    if (provided.module) return { kind: "module", moduleId: provided.module };
+  }
+
+  // Frameworks such as Django can build Swagger at runtime without keeping a
+  // document in the repository.  The extractor can still prove the routes
+  // from URLConf and DRF view declarations.  That is a partial contract worth
+  // showing, but it must not be presented as a source OpenAPI document.
+  if (service.provides.some((provided) => provided.methods.some((method) => method.http))) {
+    return { kind: "inferred-http" };
+  }
+
+  return null;
+}