v3: the docs follow deno doc's grain — the index page was a hand-kept list of some 250 links into deno doc's output layout (./api/main.ts/index.html), policed by mod.test.ts; deno doc has no module index of its own beyond all_symbols.html, which lists every module by path with its summary. mod.ts is now a prose overview of the three parts and their layers, linking that list once, and mod.test.ts is gone. Re-exporting everything from mod.ts, as deno doc's tutorial does for a library, was tried and doesn't fit: export * drops the 18 routers (default exports) and makes 17 names ambiguous, and deno 2.9 renders export * as namespaces with the root's module doc and nested ones empty, losing every module doc. A router's page showed one line: its endpoint list sat on the default symbol, whose summary was cut at the colon introducing it; the list is now the module doc of all 18 routers, and the router's JSDoc says so. 22 summaries ended in a colon (the routers, BandcampPlayer, migration 0016, useDumpListSync, usePlaylistListSync) and read cut short wherever deno doc shows a first paragraph alone; they end in a full stop, doc-lint.ts now fails on a colon summary, and the README states the rule. No behaviour changes; 204 backend tests pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

doc-lint.ts

@@ -7,6 +7,10 @@
  * whose type the module imports from a package is let through, and counted;
  * every other diagnostic fails the run.
  *
+ * It also checks what `deno doc --lint` doesn't: that every summary stands on
+ * its own. The reference shows a doc's first paragraph alone, in lists and
+ * above a symbol, so a first paragraph ending in a colon reads cut short.
+ *
  * @module
  */
 
@@ -62,8 +66,64 @@ function isPackageTypeRef(d: Diagnostic): boolean {
     importedFromPackage(d.file, type);
 }
 
+/** Returns the first paragraph of `doc`, which the reference shows alone. */
+function summary(doc: string): string {
+  return doc.trim().split(/\n\s*\n|\n\s*(?:[-*]|\d+\.)\s|\n\s*```/)[0].trim();
+}
+
+/**
+ * Returns a diagnostic for every doc among `modules`, module docs included,
+ * whose summary ends in a colon.
+ */
+async function colonSummaries(modules: string[]): Promise<Diagnostic[]> {
+  const { stdout } = await new Deno.Command(Deno.execPath(), {
+    args: ["doc", "--json", ...modules],
+    stdout: "piped",
+    stderr: "null",
+  }).output();
+  const { nodes } = JSON.parse(new TextDecoder().decode(stdout)) as {
+    nodes: Record<string, unknown>;
+  };
+  const found: Diagnostic[] = [];
+  const cwd = `file://${Deno.cwd()}/`;
+  function visit(file: string, name: string, value: unknown) {
+    if (Array.isArray(value)) {
+      for (const item of value) visit(file, name, item);
+      return;
+    }
+    if (typeof value !== "object" || value === null) return;
+    const node = value as Record<string, unknown>;
+    const at = typeof node.name === "string" ? node.name : name;
+    for (const key of ["jsDoc", "module_doc"]) {
+      const doc = (node[key] as { doc?: string } | undefined)?.doc;
+      if (doc && summary(doc).endsWith(":")) {
+        const what = key === "module_doc" ? "module doc" : `doc of ${at}`;
+        const message = `the ${what} has a summary ending in a colon`;
+        found.push({
+          rule: "colon-summary",
+          message,
+          file,
+          text: `error[colon-summary]: ${message}\n --> ${file}`,
+        });
+      }
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (key !== "jsDoc" && key !== "module_doc" && key !== "imports") {
+        visit(file, at, child);
+      }
+    }
+  }
+  for (const [url, module] of Object.entries(nodes)) {
+    visit(url.replace(cwd, ""), "", module);
+  }
+  return found;
+}
+
 if (import.meta.main) {
-  const diagnostics = await lint(Deno.args);
+  const diagnostics = [
+    ...await lint(Deno.args),
+    ...await colonSummaries(Deno.args),
+  ];
   const failures = diagnostics.filter((d) => !isPackageTypeRef(d));
   for (const d of failures) console.error(d.text.trimEnd() + "\n");
   const allowed = diagnostics.length - failures.length;